Hello there and can I please have closure comments represented or am I doing something wrong?

[michaelcoconnor]

Mr. Sushi himself asked that I explain here the problem that I am having: http://stackoverflow.com/questions/1125970/python-documentation-generator/18258983?noredirect=1#comment46361911_18258983.

Here's the requested example:

def Example( ):
'''
Some comments.
'''

def deco(funct):

    def wrapper(*args, **kargs):

        ##############################
        # start a closure

        def exampleclosure():
            '''
            Some comments about the closure.
            '''

            return "Example() was run."

        # end a closure
        ##############################

        print funct()
        print  exampleclosure()

    return wrapper  

return deco

@example()
def dummy():
return "Ran dummy."

dummy()

So yes, I do a lot of decorators. And here's the pdoc output:

nummatenv)mike@Presario:~/retailbacktest/code$ pdoc example.py
Ran dummy.
Example() was run.

Module example

Functions

Example()
Some comments.

dummy(_args, *_kargs)
(nummatenv)mike@Presario:~/retailbacktest/code$

So of course I was hoping to see some output that contains "Some comments about the closure." But there is none. (Markdown accentuates "Module example" and "Functions" due to the lines of dashes that are in the pdoc output, but you must be familiar with that.)

Thanks much for all of the good work,
-Mike

[cortesi]

I'm afraid I don't see how we can sensibly provide docs for functions in nested scope. Pdoc aims to document the public portions of an API, and inner functions like this are by definition implementation details. They are only executed at runtime, when the enclosing function is executed.