bug-texinfo
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: AW: Feature request: api docs


From: Jacob Bachmeyer
Subject: Re: AW: Feature request: api docs
Date: Fri, 25 Feb 2022 20:48:32 -0600
User-agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.8.1.22) Gecko/20090807 MultiZilla/1.8.3.4e SeaMonkey/1.1.17 Mnenhy/0.7.6.0

Ernst Reissner wrote:
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.

Now that I think about it, technically Perl does not have named parameters (they are simply positions in the incoming argument array), but convention is to unpack that array into lexicals, effectively naming the arguments (and dispelling the magic that the argument array actually holds _aliases_ to the passed values).

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.


Named return values can be treated as output parameters. Something similar occurs with non-const references in C++ and the actual arguments in @_ in Perl.

[...]
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)


For typed languages, we already have @deftypefn and its derivatives, which include a return type field as an argument, so a tool could check documentation consistency (at least for C) by simply stripping out any Texinfo markup and checking that the result matches the declared prototype.

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:

[...]

uses presentation markup like @table.

I would strongly opt for

[...]

There is a difference between markup used in a *.texi file and markup used in source comments. Since some intermediate tool must extract the latter and write a *.texi file, there would be an opportunity to translate a slightly different markup to baseline Texinfo. That intermediate tool could easily use presentation markup in its output. Also, "@table @var" somewhat straddles a line between semantic and presentation markup, due to the relatively limited notion of tables in Texinfo -- @table is more akin to an HTML definition list than it is to the LaTeX tabular environment, for example. In the context of a @deffn or @deftypefn, "@table @var" could very easily be parameter definitions.

Second, if we are proposing a documentation comment syntax, an actual @deffun or @deftypefun is redundant -- it can be extracted from the actual nearby code. For the more general @deffn and @deftypefn, we will need some way to specify the @var{category}.

Consider:

8<------
int foobar (int foo, float bar)
/** Library Function
*  #param foo: Foo parameter.
*  #param bar: Bar parameter.
*
*  #throws exception::foobar when ...
*
* Foobaricate the given parameters.  ...
*/
{
 /* implementation omitted */
}
8<------

The extraction tool would translate this to:

8<------
@deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar})
Parameters:
@table @var
@item foo
Foo parameter.
@item bar
Bar parameter.
@end table

Exceptions:
@table @code
@item exception::foobar
Thrown when ...
@end table

Foobaricate the given parameters.  ...
@end deftypefn
8<------


If there had been no further text on the /** line, @deftypefun would have been emitted instead. I also suggest using # instead of @ above simply to distinguish the API documentation syntax from the regular Texinfo syntax. Of course, regular Texinfo @-markup would be passed through.

Generally, I do not believe that inline API documentation is a good idea -- the API manual should be a specification that the code implements, and should ideally be written first to ensure that a clear goal is in mind before writing code.


-- Jacob



reply via email to

[Prev in Thread] Current Thread [Next in Thread]