[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[epsilon-devel] [task #3380] Documentation strings
From: |
Luca Saiu |
Subject: |
[epsilon-devel] [task #3380] Documentation strings |
Date: |
Sun, 08 Aug 2004 22:47:42 -0400 |
User-agent: |
Mozilla/5.0 (X11; U; Linux i586; en-US; rv:1.3a) Gecko/20021212 |
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/
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [epsilon-devel] [task #3380] Documentation strings,
Luca Saiu <=