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 <[email protected]> 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. 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 [email protected] https://lists.sourceforge.net/lists/listinfo/oorexx-devel
