[epsilon-devel] [task #3380] Documentation strings

[Luca Saiu]

This mail is an automated notification from the task tracker
 of the project: epsilon.




/**************************************************************************/
[task #3380] Full Item Snapshot:

URL: <http://savannah.gnu.org/task/?func=detailitem&item_id=3380>
Project: epsilon
Submitted by: Luca Saiu
On: Mon 08/09/2004 at 02:43

Category:  Documentation
Should Start On:  Mon 08/09/2004 at 00:00
Should be Finished on:  Mon 08/09/2004 at 00:00
Priority:  1 - Later
Resolution:  None
Assigned to:  None
Percent Complete:  0%
Status:  Open
Effort:  0.00


Summary:  Documentation strings

Original Submission:  As I'm writing the meta-interpreter and the REPL I see 
epsilon  somewhat converging to Lisp in its interface aspects. This made me 
think to a peculiarity of it which I would like to imitate.

It would be very nice to have documentation strings, as in Lisp, which could be 
displayed as *part* of the online help
in the REPL, and in the index the Texinfo documentation (for example in menus 
in Info).

When used in Emacs we could also have something like C-h f which jumps to the 
correct paragraph of the Info documentation (crosslink to paragraphs is now 
implemented in the latest version of Texinfo, se we can use it); C-h f should 
jump to the *complete* documentation for the function/object/type/exception, 
and not just the documentation string.

It is also very good for encouraging good programming syle to make a practice 
of documenting *every* function/object/type/exception, at least with 
documentation strings. The compiler could even give a warning (which could be 
disabled with a command-line option) when it doesn't find it.

Aboute the "complete", non-documentation-string documentation: we could 
automatically extract documentation for the library (and *only* for it) from 
apposite comments in the code, automatically generating the Texinfo code which 
will be included in the manual.

We should take some good ideas from JavaDoc and Doxygen; of course we are going 
to generate only Texinfo, and use it to make HTML if needed.

In JavaDoc there's a separate "index" part of very short introductive 
descriptions, and a more complete part which describes every detail. This is 
just like what I want.

I like this idea very much, and it's also easy to implement.












For detailed info, follow this link:
<http://savannah.gnu.org/task/?func=detailitem&item_id=3380>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/