Re: [Axiom-developer] Using ALLPROSE for SPAD programming

[Gernot Hueber]

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