From: Jim Freeze Date: 2002-09-18T05:37:52+09:00 Subject: Re: Another latecomer; A half-baked suggestion. On Tue, Sep 17, 2002 at 12:59:46PM -0700, Sean Chittenden wrote: > > > > Concerning everything else that you said, it seems to me that > > > > you are envisioning a system that will provide full > > > > documentation capabilities. That is, a way to write large > > > > documentation documents that can be exported to many formats. Am > > > > I correct? > > > > > > There any other kind? If you put forth a standard like POD, then > > > > Yes. Let me explain. It has been discussed that there are different > > types of documentation. Some of those listed are: API, tutorial, > > installation, users guide and reference manual. > > > Sorry, I don't understand the above. Are you saying that some XML file has a set of doc types defined? What are the '?' for? > > My point is that we don't need to put each of these types of > > documentation inside the source. (It is a matter of discussion if it > > needs to be linked from the source.) > > > Again, I'm not sure what you are saying. > > Also, to me it is not clear that all these types of documentation > > possess the same markup requirements. So, I think that a system that > > facilitates footnotes, creation of an index, bibliography and table > > of contents may be overkill for an API documentation system. > > Agreed. An API documentation system needs very little. > > *) It's parent class's name (automatically determined) > *) The method name (automatically determined?) > *) Its arguments (arity is known, but a manual description is needed) > *) Its return value (manual) > *) Exceptions a method will throw (possibly automatic, but needs manual descriptions) > *) Information about performance and resources (expensive, fast, memory, external dependencies) > > Shouldn't need any more than that. Something as simple as: > > ## > # class: Foo > # name: bar > # arg: argname, description...[newline reached] > # more description for argname > # arg: argname2, description for argname2 > # return: it's return value > # exception: Foo::ExceptionBadOne, description of exception > # exception: Foo::ExceptionBadTwo, description of exception > # notes: various performance notes > ## > This is good. This is the type of thing we need to discuss and put in the functional spec. Sean: I don't see any problem with what you are proposing. From my perspective, you are suggesting that we use docbook to create various doc outputs. Also, if rdoc export to xml, you are saying that with xml style sheets you can make that pretty too. To me this is all doable and does not need to be part of the base isntall, but can be installed as a 3rd party doc tool. Since you are so active with this, I want to make sure we take your ideas into consideration so that in the least we do not inhibit the use of this feature rich functionality and at the most that the standard doc system works cooperatively with such a document system. But this brings up the issue that was skirted, and that is exactly how do we support both. It could be as simple as the doc writer uses simple ML or docbook for external documents. The simple ML for more routine work and docbook for larger doc projects. Also, I suppose that for a system to work cooperatively that a way be provided that an external doc system could fetch the internal api docs automatically. Whether that means that the standard doc system export that information or a tool/module be provided to access the information remains to be determined. -- Jim Freeze ---------- Programming Ruby def initialize; fun; end A language with class ----- End forwarded message ----- -- Jim Freeze ---------- Programming Ruby def initialize; fun; end A language with class