Hi Ralf,
On Tue, 2006-08-22 at 14:18 +0200, Ralf Hemmecke wrote:
> > 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.
I agree with you, most important is the API _together_ with a
description and examples, not the actual implementation. From my
experience far too often even the API is badly documented. In this case
a half of the story solution is much better than none at all.
>
> 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.
Yes, you are right, I am/was too much focused on the API.
Thanks for your comments.
Gernot
>
> Ralf
_______________________________________________
Axiom-developer mailing list
Axiom-developer@nongnu.org
http://lists.nongnu.org/mailman/listinfo/axiom-developer
