Hello all,
I wonder if a tool (a la Javadoc) for generating XML/HTML
documentation from Lisp sources exists??
All Lisp projects really lacks API documentation. If we give a look at
all others projects in other languages, for example the Gnome/Gtk/Glib
libraries, they have great looking documentations generated with tools
like Doxygen or Javadoc... Each time I get some Common Lisp code from
the net, I must read the code to get some informations about its APIs,
it's really boring. I think such a tool is not difficult to write in
CL and will be really interesting for all the CL community and help
sharing libraries... Technically, XML could be generated using MOP for
compiled code and direct lisp objets for source code. The XML document
could then be transformed using XSLT sheets to produce HTML, plain
text or LaTeX documents.
······@mail.dotcom.fr (Frederic Brunel) writes:
> Hello all,
>
> I wonder if a tool (a la Javadoc) for generating XML/HTML
> documentation from Lisp sources exists??
>
> All Lisp projects really lacks API documentation. If we give a look at
> all others projects in other languages, for example the Gnome/Gtk/Glib
> libraries, they have great looking documentations
I don't know about the Glib docs being great, but they are there.
It's true that a lot of free lisp projects are insufficiently
documented. I don't think this is a tool problem as much as it is a
manpower and priority problem. If you looked at the Gnome, GTK, and
Glib documentation 4 years ago, it was aweful/absent. With all the
manhours thrown at that project since then, it would be inexcusable if
they didn't have decent docs. And FWIW, I'm still not very impressed
with their docs.
It would be quite simple to write a tool to generate skeleton
documentation from the docstrings of a package or file. Such a thing
exists for Emacs, but it's hardly a panacea for documentation
problems. Even with as strong a community value placed on
documentation as is there, look at the Eshell non-docs.
--
/|_ .-----------------------.
,' .\ / | No to Imperialist war |
,--' _,' | Wage class war! |
/ / `-----------------------'
( -. |
| ) |
(`-. '--.)
`. )----'
> I don't know about the Glib docs being great, but they are there.
> It's true that a lot of free lisp projects are insufficiently
> documented. I don't think this is a tool problem as much as it is a
> manpower and priority problem. If you looked at the Gnome, GTK, and
> Glib documentation 4 years ago, it was aweful/absent. With all the
> manhours thrown at that project since then, it would be inexcusable if
> they didn't have decent docs. And FWIW, I'm still not very impressed
> with their docs.
Yes, I agree with you, such a tool is not the ultimate solution for
writing good documentation but its the way to it. Look the work Sun
has done with Java. Giving a standard documentation tool with all its
JDKs from the beginning helps to write APIs documentation which looks
the same as the core Java docs. Thus, everybody seems very comfortable
with the Javadoc navigation and I thinks its very important. Java
projects are now probably the most documented ones. The first time
I've looked at Java, I've said "Wow it have a great documentation
which seems very complete, I wonder if I will be able to do the same
for my own documentations". Writing API documentations for developers
is boring, IMHO a tool which ease its writing is really usefull.
Mostly all other documentations systems like Doxygen or the one used
for Gnome are derivated from the Javadoc.
> It would be quite simple to write a tool to generate skeleton
> documentation from the docstrings of a package or file. Such a thing
> exists for Emacs, but it's hardly a panacea for documentation
> problems. Even with as strong a community value placed on
> documentation as is there, look at the Eshell non-docs.
A package should always be released with its complete API
documentation or the lists of its exported functions. Using Lisp we
could list classes, structures, methods and functions names and
arguments.
--
Frederic Brunel
······@mail.dotcom.fr (Frederic Brunel) writes:
> > I don't know about the Glib docs being great, but they are there.
> > It's true that a lot of free lisp projects are insufficiently
> > documented. I don't think this is a tool problem as much as it is a
> > manpower and priority problem. If you looked at the Gnome, GTK, and
> > Glib documentation 4 years ago, it was aweful/absent. With all the
> > manhours thrown at that project since then, it would be inexcusable if
> > they didn't have decent docs. And FWIW, I'm still not very impressed
> > with their docs.
>
> Yes, I agree with you, such a tool is not the ultimate solution for
> writing good documentation but its the way to it. Look the work Sun
> has done with Java. Giving a standard documentation tool with all its
> JDKs from the beginning helps to write APIs documentation which looks
> the same as the core Java docs. Thus, everybody seems very comfortable
> with the Javadoc navigation and I thinks its very important. Java
> projects are now probably the most documented ones. The first time
> I've looked at Java, I've said "Wow it have a great documentation
> which seems very complete, I wonder if I will be able to do the same
> for my own documentations". Writing API documentations for developers
> is boring, IMHO a tool which ease its writing is really usefull.
> Mostly all other documentations systems like Doxygen or the one used
> for Gnome are derivated from the Javadoc.
>
> > It would be quite simple to write a tool to generate skeleton
> > documentation from the docstrings of a package or file. Such a thing
> > exists for Emacs, but it's hardly a panacea for documentation
> > problems. Even with as strong a community value placed on
> > documentation as is there, look at the Eshell non-docs.
>
> A package should always be released with its complete API
> documentation or the lists of its exported functions. Using Lisp we
> could list classes, structures, methods and functions names and
> arguments.
Yes, but if that's all the documentation is, it doesn't sound any
better than docstrings. If someone writes nice docstrings -- a feat
easier than using javadoc, imo -- the user can load the package into a
running Lisp and poke around, see what's exported, and read the
documentation on those things. If you're going to the trouble to make
real documentation, it should be better than this. A good way to
start might be to dump all the docstrings, but that's nowhere near the
end.
--
/|_ .-----------------------.
,' .\ / | No to Imperialist war |
,--' _,' | Wage class war! |
/ / `-----------------------'
( -. |
| ) |
(`-. '--.)
`. )----'
On 26 Dec 2001 14:49:15 -0800, ······@mail.dotcom.fr (Frederic Brunel)
wrote:
> I wonder if a tool (a la Javadoc) for generating XML/HTML
> documentation from Lisp sources exists??
There have been recent discussions about this issue in comp.lang.lisp. You
may search for "adg", "automatic documentation generators" or "javadoc" via
Google Groups. See in particular articles <················@naggum.net> and
<··············@orion.bln.pmsf.de>.
Paolo
--
EncyCMUCLopedia * Extensive collection of CMU Common Lisp documentation
http://web.mclink.it/amoroso/ency/README
[http://cvs2.cons.org:8000/cmucl/doc/EncyCMUCLopedia/]
> There have been recent discussions about this issue in comp.lang.lisp. You
> may search for "adg", "automatic documentation generators" or "javadoc"
via
> Google Groups. See in particular articles <················@naggum.net>
and
> <··············@orion.bln.pmsf.de>.
Thanks, I've read the post from Pierre R. Mai... His arguments about good
docs
are very persuasives. Afterall, maybe an ADG is not a good thing since any
Lisp
environment provides dynamic mechanism for querying functions informations.
I also agree that source code doc it not sufficient for a project
documentation.