First of all, I want to point out that I don't want to advocate against
ALLPROSE for documentation, which is in fact an interesting development
framework.
Nevertheless, my contribution do the documentation discussion is
non-ALLPROSE. Did you consider using an "javadoc" style for
documentation.
Of course. You certainly know about the +++ comments. These things have
been invented before Java came into existence. The only problem with
Aldor is that there is not yet a proper tool to make use of this data.
ALLPROSE hast \begin{+++} ... \end{+++} for that.
> E.g. doxygen is a mature and flexible tool aimed primary
at C++ but extended to some more languages.
Yep, doxygen is too much tailored for C/C++. If you make it work for
Aldor, it might be worth another try.
But as Tim suggests, that is not the point of literate programming. LP
is here to express your ideas and illustrate these ideas by real (in
contrast to pseudo) code. So you basically write a research article (or
so). In that sense I fully support Tim and Knuth.
But as you can see with my \begin{+++} ... \end{+++} environments, I
also strongly believe that for using other peoples work it is often
quite sufficient if you know about the API of what that library/program
does on which you want to build. You do not usually want to read
thousands of pages and books before you are able to write one single
line of code.
I, for example, would be quite happy if someone writes a library for
factorization of multivariate polynomials in an LP style and
additionally gives me a short API description of what his function does
and how I have to call it. I am simply not interested in learning all
the difficult stuff about an efficient implementation and about tricks
in this implementation to make it even more efficient. I want to use
factorization. If I ever become interested in the details, I can come
back to that later.
So my approach in ALLPROSE is to write in an LP style and *additionally*
provide an API description for those who don't want to delve too deeply
into the details.
If you can make some tool available that supports such a combined
approach, I would be quite happy to see them.
But I would never sacrifice the LP approach to doxygen. Doxygen (to my
taste--correct me if I'm wrong) is only about the API, ie half of the
story -- if not less.
Ralf
_______________________________________________
Axiom-developer mailing list
[email protected]
http://lists.nongnu.org/mailman/listinfo/axiom-developer
