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

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

On Sat, Jul 7, 2012 at 5:20 PM, Mark Miesfeld <mie...@gm...> wrote:
> Yeah, this is a good thing to talk about.  I have some related
> questions I was going to bring up some time soon.  Related because
> they concern extensions.
>
> See inline for the documentation topic.
>
> On Sat, Jul 7, 2012 at 1:17 PM, Rick McGuire <obj...@gm...> wrote:
>> 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?
>
> I would lean towards a separate extensions reference library for
> non-core extensions, that are shipped as part of the distribution.
> Especially to group together the smaller extensions.
>
> For bigger extensions, and I guess I mean bigger in the sense that the
> reference is bigger, for some of those I think a separate reference
> still make sense.
>
>> 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.
>
> We have already started towards this, maybe we just need to formalize it a bit.
>
> Several releases ago, I pulled most of the doc for the smaller Windows
> only extensions into winextensions.pdf.  Then David started
> unixextensions for Unix specific extensions.  And we have
> rexxextensions.pdf for platform independent extensions.  These make a
> good separation in my mind.
>
> rexxextensions.pdf currently has the doc for CVSStream and HostEMU.
> It seems to me that rxmath, regexp, rxftp, and rxsock documentation
> could all be moved into rexxextensions.
>
> As for a separate doc for each library, I think that depends on the
> extension.  If the size of the doc for an extension by itself is 4 or
> 5 MB, than I think that justifies a separate doc.  On the other hand,
> a size like 275 KB, like rxmath, would indicate it was a good
> candidate to be merged into one of the other docs.
>
>> 2)  How much to document?
>
> Yeah, that's the big question.  ;-)
>
>
>> 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!).
>
> That seems to make sense for what you are working on now.
>
> I'm aware that you know better than I that you don't want to document
> how things are implemented internally when the internal implementation
> is subject to change.  So, in this case if the implementation classes
> are not something the users would be expected to subclass, or change
> in any way, or need to directly invoke the methods of, then yeah I
> think you're right they should be left undocumented.
>
> Related to this, how much to document, is what documentation is
> already available and how easy is it to access?
>
> For example, for ooSQLite, many of the methods of the objects are just
> a one-to-one mapping of a SQLite API.  The SQLite APIs are well
> documented and easy to access online.  It doesn't make sense to me to
> just copy the SQLIte API doc into the ooSQLite doc.  And yet the
> suggestions I've made in the past that users of ooDialog just look up
> something in the Microsoft documentation, were poorly received.

Ah, I knew I had a third point I wanted to bring up!  Similar to your
SQLite problem is the question of how much document for standardized
stuff.  A good example are XPath expressions.  This is essentially a
programming language in its own right.  It would be quite a task to
write an ooRexx-only version of XPath expression docs without running
into copyright problems with other works.  I suspect we'll
increasingly find ourselves in the position of just giving pointers to
various references, spec, or tutorials that exist on the web for
documenting things like this.

Rick

>
> For your 2 questions, ultimately you'll probably need to decide for
> yourself, but it seems to me the doc for XMl might be substantial
> enough to justify its own reference.  I'd be in favor of gathering up
> the smaller doc we already have and putting it into the
> rexxextensions.pdf, moving the regexp doc out of the main rexxref doc,
> etc..  There is a certain amount of boiler plate text that can be
> reduced by having the doc for smaller extensions in one book rather
> than a number of small books.
>
> Going forward, I'd like write more extensions.  I think one of the
> things that makes perl popular is that you can find a module to do
> most anything you need.  So, I think adding more extensions that
> people can get off of SourceForge would be a benefit for ooRexx.  As
> the extensions are written we can decide if the doc should go into one
> of the common references already started, or into its own reference.
>
> --
> Mark Miesfeld
>
> ------------------------------------------------------------------------------
> Live Security Virtual Conference
> Exclusive live event will cover all the ways today's security and
> threat landscape has changed and how IT managers can respond. Discussions
> will include endpoint security, mobile security and the latest in malware
> threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
> _______________________________________________
> Oorexx-devel mailing list
> Oor...@li...
> https://lists.sourceforge.net/lists/listinfo/oorexx-devel