AW: Feature request: api docs

[Reißner Ernst]

> It seems to me that what is in the numpydoc specification is somewhat too 
> specific to be
> relevant for Texinfo.  However, I also think that we should make sure that a 
> corresponding 
> formatting can be achieved, even if without some specific semantic.  It seems 
> to me that almost 
> everything is available, though I may have missed something.

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. I can see that @example is satisfactory and @var and others 
also. 

> There aren't references in Texinfo, but if added, it should be more 
> generically available, 
> not only for methods documentation.  I think that this one is in a TODO, 
> actually.

I see. 


> Of course, all that lacks semantic. One could imagine having, instead of 
> @table, @parameters, or maybe @ptable which would be formatted like a table.  
> An indicator functions for a type, like @type{} to use instead of @code could 
> also be added.  As the formatting can already be done in Texinfo, the main 
> issue to me is where to stop in term of semantic markup.  And I do not think 
> that we should add new markup especially for the formatting of functions, but 
> with a more general view on the usefulness of more markup in other contexts 
> too. 

I can see the problem. 
@type maybe a good idea but not strictly necessary. 
@param would be fine, I could not find @parameter in the manual. 
Maybe that is the only thing missing as @error exists and @result. 


> I agree that there is nothing existing as a container for multiple @def* that 
> could be used for class or package.

Yes this is really needed. 

Ernst