#288 Epydoc incorrectly links method parameters to attribute doc

v3.0
closed-works-for-me
5
2008-08-22
2008-08-22
Anonymous
No

If a parameter of a class method has the same name as an instance attribute of the class, Epydoc 3.0 beta1 incorrectly hyperlinks the parameter name to the attribute documentation in the generated HTML. For example, for the class:

class EpydocProblem(object):

def __init__(self, bobo):

'''
Initializes this `EpydocProblem`.

**Parameters:**

- `bobo` - documentation for parameter `bobo`.
'''

self.bobo = bobo
'''documentation for attribute `bobo`.'''

in the generated HTML the method parameter "bobo" is hyperlinked to the documentation for the instance attribute "bobo".

If possible, please let me (harold.mills at gmail.com) know when this problem is fixed. And thank you very much for epydoc!

Discussion

  • Nobody/Anonymous

    Logged In: NO

    Sorry, I realized after I submitted the above that the example is not as clear as it should have been. So here's another try. In the HTML documentation that epydoc generates for the following:

    class EpydocProblem(object):

    def __init__(self, bobo):

    '''
    Initializes this `EpydocProblem`.

    **Parameters:**

    - `bobo` - parameter documentation.
    '''

    self.bobo = bobo
    '''attribute documentation.'''

    the name of the method parameter "bobo" is hyperlinked to the documentation for the attribute "bobo".

    Harold Mills

     
  • Edward Loper

    Edward Loper - 2008-08-22

    Logged In: YES
    user_id=195958
    Originator: NO

    Solution 1: use the standard syntax to list parameters, rather than an ad-hoc one. See <http://epydoc.sourceforge.net/fields.html#rst> I.e.:

    :Parameters:
    - `bobo` - parameter documentation.

    (n.b. that the list of parameters needs to be indented relative to the ":Parameters:" heading for rst to consider it to be "inside" it.)

    Solution 2: use ``bobo`` rather than `bobo` if you don't want epydoc to try to automatically link to something called "bobo".

    There's really no way for epydoc to know which version of bobo you mean when you say `bobo`, so it makes the (reasonable) assumption that it's the one that might be useful to link to. That way, you can link to that (the variable) if you want; or you can give the name of the parameter by just saying ``bobo``.

     
  • Edward Loper

    Edward Loper - 2008-08-22
    • status: open --> closed-works-for-me
     

Log in to post a comment.