[Doc-SIG] Undocumented modules

Fred L. Drake Fred L. Drake, Jr." <fdrake@acm.org
Wed, 24 Feb 1999 09:28:19 -0500 (EST)

skip@mojam.com writes:
 > I think there's a logic bug.  The posixpath module is documented at
 >     http://www.python.org/doc/lib/module-posixpath.html

  No, that's left over from the previous version of the documentation; 
I'll remove it... done.  The index of documented modules doesn't list
posixpath, and probably shouldn't; it is listed as an undocumented
implementation detail.  See:


  (On the other hand, I just used it explicitly for something where
that made sense.  Perhaps each of the *path modules should be
documented, but only say that it's an implementation of os.path for
the specific OS; there are times when this is exactly what's needed.)

 > Also, some minor modules that only define manifest constants (SOCKET, ERRNO,
 > regex_syntax all come to mind) probably aren't worth mentioning outside the
 > documentation of other modules (socket, errno, regex, respectively).  ERRNO,
 > in particular, seems to be sucked into errno in its entirety, so probably

  ERRNO is not sucked into errno.  The identity match for small
integers is due to the small integers cache maintained internally to
Objects/intobject.c as a performance improvement.
  I'd like to see modules that consist only of constants for use with
other modules folded into those modules and removed.  If the module is 
something that the user is expected to import, it should be
documented, even if trivially:



Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191