-----Ursprüngliche Nachricht-----
Von: Patrice Dumas <[email protected]>
Gesendet: Samstag, 19. Februar 2022 15:55
An: Reißner Ernst <[email protected]>
Cc: [email protected]; [email protected]
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
