Re: AW: Feature request: api docs

[Ernst Reissner]

Hello Jacob,

> Reißner
>       Ernst wrote:
>       
> > [...]
> >         
> >         All of these markup is not presentational like @table, it is
> >         content markup, descriptive or even procedural. It allows other
> >         tools not only to render, but to analyze and to verify. 
> >         I also strongly disagree that this kind of markup is really
> >         language specific. Parameters, returns and exceptions are
> >         present in all usual languages. Parameters are always named.
> >         
> >           
>       
>       They are not named at all in Forth.  They are simply relative
>       positions on the stack.  (They could be named in a comment or
>       documentation, but this has no meaning in the language itself.)
>       
>

I agree, that my suggestion does not apply to forth.
But even for forth one could find a solution:
parameter names shall be optional depending on the language.
I suggest, there shall be a parameter if one wants to include forth also.
I think most languages do have parameter names.

For return values, the according flexibility is much more important:

• most languages have a single return value only and there is no parameter name.
  
• Nevertheless, matlab allows multiple return values and it is reasonable to make return values named in general.
  

>       
>       In the other direction, in Objective-C, parameter names are part
>       of method names; two methods with the same parameters in a
>       different order are distinct methods.  In Common Lisp, parameters
>       can be positional or tagged; the order of tagged parameters is not
>       significant in a call.  In Perl, tagged parameters are sometimes
>       emulated by constructing an associative array from the argument
>       list.
>       
>

I think in any case one could get along with named parameters. Even for forth one could do that,
even though names do not show up in the code.
I would strongly opt for that.
It helps avoiding mistakes.

>       
> > Exceptions may have a type or not, Only
> >         return values are somehow a bit inhomogeneous: Most language
> >         allow a single return value, others allow multiple ones.
> >         
> >         Some have named return like parameters. But all in all I think
> >         one could reach easily a uniform set of markup serving 98% of
> >         languages.
> >         
> >       
>       
>       Overall, this does seem somewhat reasonable, and we could probably
>       cover all or nearly all languages with a fairly simple model.  The
>       existing @deffn and @deftypefn functions already take names for
>       arguments and a return type in the latter case.  As I understand,
>       convention is to describe the return value using a sentence
>       "Return ..." or "Returns ..."; both of these are fine in free
>       text.
>       
>

java: return

c++ return and returns

python: returns

c#: returns

Well, we could do both.

>       
>       While writing the above, I noticed that we seem to already be
>       almost all of the way there.  Are you requesting some kind of
>       semantic parameter table be added?  Just name/description pairs? 
>       The parameter types are already in the argument list with
>       @deftypefn and its derivatives.  Why not simply use "@table @var"
>       for this purpose?
>       
>

This is bad.

For several reasons.

One of them: check consistency by tool.

- coincidence of signature and @deffn,

- coincidence of names in @deffn and in param and in return(s)

Also the tool to create the output shall be free how to display, it is matter of stylesheet in general.

As you can see, none of the tools I mentioned above:

- doxygen, javadoc for java

- doxygen for c++

- sphinx for python

- internal for c#

uses presentation markup like @table.

I would strongly opt for

@param name: @c{optional}

<explanation>

@end param

and accordingly for the return value, maybe @return.

For exceptions sometimes these are typed

so appropriate is

@throws classname:@c{optional}

<when it is thown>

@end throws

By the way: the presence of @var{...} is very good. That way one could reference parameters
and find inconsistencies.

Best Regards,

Ernst

>       
>       
>       -- Jacob
>       
>       
>       .
>       
>