[FRPythoneers] POD vs. JavaDoc

Sean Reifschneider jafo at tummy.com
Fri Apr 7 02:47:06 MDT 2000


Greetings.  Below are some of my thoughts on the Python documentation
project.  I'd appreciate comments.  I'd like to have a design available
so that we can have a party on April 15 or 16 to hammer it out.  Any
suggestions on what days are best for folks?  I'm thinking Sunday
because it's usually kind of a lazy day anyway.

I've done some looking at POD (since I'm not at all familiar with it).
It seems mostly that Perl's Plain Old Documentation (POD) is used for
embedding unix-style man-pages into the source code.  While man-pages
have their place, I don't think that modules with classes and methods
is one of them.

POD does have some neat tools though.  "perldoc" can be used kind of
like "man".  For example "perldoc Net::Ping" produces the manpage for
the Ping sub-module of Net.  However, "perldoc Net" doesn't return
anything.  There's also pod2html for converting a module into an
HTML file.  The output of this is little more than a man page
formatted for HTML

POD looks like:

	=head1 NAME

	Net::Ping - check a remote host for reachability.

	=head1 SYNOPSIS

		 use Net::Ping;

		 $p = Net::Ping->new();
		 [...]

	=head1 DESCRIPTION

	[...]

I don't really feel that the POD stuff is what I'd find the most useful.
In particular, it doesn't seem to have any way to describe individual
classes or methods in such a way that you can programaticly access it
later.

Unlike POD, JavaDoc seems to have a *LOT* of *VERY* specific documentation
about it's use (http://java.sun.com/products/jdk/javadoc/).  It includes
various guidelines for making the most of it as well.

JavaDoc borrows from HTML in many things (like using <P> to mark paragraphs
in the descriptions).  It's also fairly light-weight, picking up many of
it's cues automaticly.  For example, the first sentence is the summary.
The remaining text in the description is the full description of the
class/module/method.  

It uses <CODE> and </CODE> to mark code blocks and arguments in
descriptions.   It also supports links to other sections of the
documentation, and regular hypertext links.

There are also a number of tags available for marking things up:

	* @author       (classes and interfaces only, required)
	* @version      (classes and interfaces only, required)
	* @param        (methods and constructors only)
	* @return       (methods only)
	* @exception    (@throws is a synonym added in Javadoc 1.2)
	* @see          
	* @since        
	* @serial       (or @serialField or @serialData)
	* @deprecated   (see How and When To Deprecate APIs)

For example, one can describe parameters, exceptions thrown, and
return codes.  Personally, I'd like to see @author and @version
picked up heirarchicly so you can define it at a module
or package scope and have it's members pick up the default unless
otherwise defined.

Also, JavaDoc uses "/**" to start a javadoc comment, and "*" on each line
of the comment.  One interesting thing that would give us is the
ability to distinguish the block-level indentation from comment
indentation.

Something like:

	def extractLine(data):
		'''##
		#  Return the next line from <code>data</code>, and the remainder
		#  of the data.  Any lines terminated with \r, \n, or \r\n
		#  are broken out and returned.
		#  <P>
		#  Example:
		#
		#    <code>
		#    data = data + stdin.read(500)
		#    while 1:
		#      line, data = extractLine(data)
		#      if not line:
		#        break
		#      print 'line: "%s"' % line
		#
		#  @returns A tuple containing (1) the line from data or None if
		#           not present, and (2) remaining bytes from <code>data</code>.
		#  @exceptions None generated internally.
		#  @param data A character string to parse.
		'''
		[code...]

The thing I like about Structured Text is that it's very light-weight.
The word "example" followed by a colon beins a code block.  Indented
lines beginning with '-' are turned into unordered lists, etc.  However,
some of those things depend on indentation which may not be preserved:

		def sample(foo):
			'''This first line has no indentation.
			This next line has some.
			'''

The less tagging you have to do, the more readable it is.  However, the
less tagging available, the less descriptive it is.  However, I think it's
worth considering using ``paramname'' in the description to be
equivalent to <code>paramname</code> (and much more readable IMHO).

Here are some things which would be nice to see:

	<example></example> tags.  Examples are often useful enough that it's worth
	tagging them individually.

	@param modifications to include:
		@param name description...
		@param name = value description... (arguments with default values)
		  or
		@param name (optional) description... (is this redundant to above?)

For the tool interface, I think there are two uses that are important:

	Documentation generation -- Build a bunch of HTML documents.

	Class Browser -- Pulling specific documentation at the user's request.

It'd be nice if we had some sort of command-line like POD where we could
say "pydoc string.find" and get the descriptions for string.find.  This
should be generalizable enough that the command-line would just be a
wrapper around methods that could also be shoved into a regular class
browser.

QUESTIONS:
	Does JavaDoc seem like the right approach to take?  If not, why and
	what's better?

	What about the "'''##" to mark a "pydoc" string?

	What about '#'s in the pydoc strings to mark "beginning of line"?

	What sort of backwards compatibilty do we want?  I'm thinking that
	any unknown documentation we take pretty much at face value and
	the command-line tool just dumps it out.  No markup available.
	The Documentation Generation would just ignore it.

Comments?

Sean
-- 
 The day that Linux invades the desktop market is the day that I start
 believing in people again.
Sean Reifschneider, Inimitably Superfluous <jafo at tummy.com>
URL: <http://www.tummy.com/xvscan> HP-UX/Linux/FreeBSD/BSDOS scanning software.




More information about the FRPythoneers mailing list