Re: Doc: make python function/method descriptions look as in Python

[Pedro Alves <pedro@codesourcery.com>]

On Friday 02 September 2011 16:12:39, Paul_Koning@dell.com wrote:
> From: Pedro Alves [mailto:pedro@codesourcery.com] 
> >On Thursday 01 September 2011 21:52:59, Paul_Koning@dell.com wrote:
> >>... 
> >> -@findex gdb.post_event
> >> +@findex gdb.post_event ()
> >>  @defun post_event event
> >
> >Judging from the other changes, I believe you meant to update defun instead of findex here.
> 
> Yes, thanks.
> 
> >IMO, it would make sense to explicit the module as well, like in the findex.  It's how e.g., <http://docs.python.org/library/time.html> looks.
> 
> Ok.  What about members?  They are marked as such (e.g., "instance variable of Value" or "Method on Value") but the name itself appears without the class name.  On the other hand, the Python docs put the class name on the member name, for example http://docs.python.org/library/logging.html 

I'd give them the same treatment.  Does @defun/@defivar/@defmethod bring
in any advantage?  IIUC, these are more useful for describing
objects/functions in a language agnostic manner.  All those "Method on Value:"
look redundant to me after converting to python syntax, as it can be
clearly infered from the syntax that we're talking about a method.  A
really-from-a-distance IMO.  Don't read any of it as requirement or
real review.

-- 
Pedro Alves