AW: Feature request: api docs

[Reißner Ernst]

-----Ursprüngliche Nachricht-----
Von: Patrice Dumas <pertusus@free.fr> 
Gesendet: Samstag, 19. Februar 2022 15:55
An: Reißner Ernst <Ernst.Reissner@corpuls.com>
Cc: bug-texinfo@gnu.org; rei3ner@arcor.de
Betreff: Re: Feature request: api docs

On Mon, Feb 07, 2022 at 08:30:15AM +0000, Reißner Ernst wrote:
> 
> Well, I think texinfo was used for general api docs but mostly lisp. 
> I think you are right, there are many features which allow also 
> formatting Of api docs, but as you say, without semantics.
> I think it is a bad idea, to put parameters in a table. 
> Relevant is that there is a parameter. 
> That way another tool can also check whether docs is complete and 
> consistent With the code.

>If this is the issue, I do not think that having specific formatting in 
>Texinfo is the way to go.  If you look at the numpydoc > example, there is no 
>semantic formatting at all.  It is reStructuredText without semantics.  The 
>semantics are added by > the specific names used in the text, and a structure 
>is mandated too (maybe more for easy parsing than for the 
> semantics).  This can already be done in Texinfo and should probably be done 
> that way, as there is no way Texinfo could > have specific markup adapted to 
> all the languages.

I researched the most common python styles: 
Google
"""Gets and prints the spreadsheet's header columns

Args:
    file_loc (str): The file location of the spreadsheet
    print_cols (bool): A flag used to print the columns to the console
        (default is False)

Returns:
    list: a list of strings representing the header columns
"""
reStruturedText
"""Gets and prints the spreadsheet's header columns

:param file_loc: The file location of the spreadsheet
:type file_loc: str
:param print_cols: A flag used to print the columns to the console
    (default is False)
:type print_cols: bool
:returns: a list of strings representing the header columns
:rtype: list
"""

Numpy
"""Gets and prints the spreadsheet's header columns

Parameters
----------
file_loc : str
    The file location of the spreadsheet
print_cols : bool, optional
    A flag used to print the columns to the console (default is False)

Returns
-------
list
    a list of strings representing the header columns
"""

Epytext: 
"""Gets and prints the spreadsheet's header columns

@type file_loc: str
@param file_loc: The file location of the spreadsheet
@type print_cols: bool
@param print_cols: A flag used to print the columns to the console
    (default is False)
@rtype: list
@returns: a list of strings representing the header columns
"""

I feel numpy is out of line and if I have a view on other language, this is 
acknowledgement. 

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. 
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. 


Best Regards, 
Ernst 


--
Pat