I want to propose that we us the following file header and function template
(in perl's POD format) to document the LXR source code. Tried to keep it
simple as possible.
# File Header
Purpose of functions in this file
# End File Header
# Function Header
=head3 function name
Desciption of function
#End Function Header
html documentation can then be generated by doing:
pod2html pod2html --title="LXR Source - genxref" --infile=filename
I'll write a perl script to call this command for each perl file.
Have a look at http://www.zeta.org.au/~nbsethna/genxref.html to see an
(empty) example of the html output.
II'll be away next week so I won't be able to reply to any email till the
following week, after which I shall be producing html pages earnestly ;-)
"Sethna, Zubin (RSA, Brisbane)" wrote:
> I want to propose that we us the following file header and function template
> (in perl's POD format) to document the LXR source code. Tried to keep it
> simple as possible.
This looks good and simple which is always an advantage. Being an OO
system there are lots of classes in the lxr - do you have a suggestion
for documenting them? I don't know what the Perl Way is for this.
For example, what I'd really like to do (actually see done :-) is
documentation for each of the "base" classes Index, File & Lang to
define what the methods are and what the usage/expected return values
are. At the moment it's only possible to deduce this by looking at one
of the derived classes, which risks confusing the interface and the
implementation. I was considering adding empty functions to the base
classes as placeholders for derived code & possibly as a place for the