Help save net neutrality! Learn more.
Close

#210 non-standard fields in "faked function" documentation

devel (cvs)
closed-fixed
3
2007-09-23
2007-07-07
No

Please see the attached small module.

Discussion

  • Paul Pogonyshev

    Paul Pogonyshev - 2007-07-07

    An example, showing the difference

     
  • Edward Loper

    Edward Loper - 2007-07-25
    • priority: 5 --> 3
     
  • Edward Loper

    Edward Loper - 2007-07-25

    Logged In: YES
    user_id=195958
    Originator: NO

    I *believe* that the problem that this bug is reporting is that there's an inconsistency in the way that the return values are shown in the details section. In particular, the example file contrasts the way the return value of the builtin 'callable' displays with the way an epytext '@rtype' field displays. These differences are actually coming from two sources:

    1. For the builtin callable(), the return value is extracted from the first line of the docstring, and placed in the 'return' field of the documentation object. But the user's function uses the '@rtype' field, which puts its string in the 'return type' field. Changing the user's function to '@return' makes the two examples look more similar in their output.

    2. For the builtin callable(), epydoc assumes that the docstring is formatted as plaintext, and so renders it using a fixed-width font. But for the user function's docstring, epydoc knows that the markup is epytext, and renders the output using a variable-width font.

    I certainly wouldn't mind patches that make these two cases look more similar, but I doubt I'll have time to fix it myself anytime soon.

    If I misunderstood the problem you're reporting, please let me know; and in the future, please include at least a sentence or two describing the problem -- it's not always possible to tell by just looking at an example python file.

     
  • Paul Pogonyshev

    Paul Pogonyshev - 2007-07-26

    Logged In: YES
    user_id=1203127
    Originator: YES

    Sorry for making you guess what I find strange here. But yes, your analysis is correct. I don't see a way to fix the second problem, but the first one must be easy. Note that it also causes one more strangety: return type of such a function is not shown in the top concise list of all functions. I.e. I have just "is_callable(object)", but "bool | real_function(object)" there.

     
  • Edward Loper

    Edward Loper - 2007-09-23
    • status: open --> closed-fixed
     
  • Edward Loper

    Edward Loper - 2007-09-23

    Logged In: YES
    user_id=195958
    Originator: NO

    Fixed in svn revision 1613.

     

Log in to post a comment.