Another latecomer; A half-baked suggestion. 
Author Message
 Another latecomer; A half-baked suggestion.


> > > > 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.

> <!ELEMENT doc (meta,introduction?,tutorial?,install?,api?,config?,sysadmin?,devhelp?,examples?,misc?,bugs?,history?,user_contrib?)>

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.)

> <!ELEMENT api (ruby_global_vars?,ruby_class_public_api?,ruby_class_protected_api?,ruby_class_private_api?,ruby_instance_public_api?,ruby_instance_protected_api?,ruby_instance_private_api?,ruby_instance_vars?,c_headers?,c_so_libs?,c_api?)>

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

Sun, 06 Mar 2005 04:42:10 GMT  
 [ 1 post ] 

 Relevant Pages 

1. Enhancement suggestion (half-baked)

2. Database half-baked?

3. Saving half-baked tcl scripts

4. lsort Half Numerical Half Text

5. half object/half dictionary

6. Texture Baking for VRML Scene?

7. Looking how to draw a half circle

8. Loop Question - Only getting half the records

9. C4b ABC - Report shifts half a page to the right

10. Closing window half way through OK button using ABC/Update Templates

11. ANN:Get gReg at HALF PRICE!

12. Sather 0.5: half way to Sather 1.0 -- sort of


Powered by phpBB® Forum Software