[Oorexx-devel] Discussion: Documentation for non-core class libraries

[Rick M. <obj...@gm...>]

I've been making a fair amount of progress on writing some classes to
add xml support to ooRexx.  This support includes a sax-like parser, a
dom implementation, a dom parser, and xpath search capability.  I
still have a lot of unit tests to write for this support, and of
course, still have documentation to write.  The documentation part
raises a number of questions.

1)  Where should information like this go?  These are going to be
non-core classes (not part of rexx.img and pulled in using
::requires)?  Should they be a chapter in the reference, in a separate
reference just for these classes, or should we consider creating an
extensions reference where libraries like this are added?

We sort of have a hodgepodge at the moment.  rxrexexp is documented as
a utility class in the ooRexx reference, while rxftp is documented in
a separate document.  The XML support documentation will be fairly
large, so I'm not sure it should be placed there.  I'm also not really
that comfortable with creating a new document for each library.  This
might be a good time to consider reorganizing things again.

2)  How much to document?  The XML support will have a lot of
interface classes that define the public interfaces, plus a ton of
implementation classes that implement those interfaces.  Documenting
everything would make things look needlessly complicated.  The target
users of these class would only be using the methods defined in the
interfaces.  I think I'd really prefer to leave the implementation
classes undocumented (and not just because that shortens my writing
task!).

Rick