pycco-docs / pycco

Literate-style documentation generator.
https://pycco-docs.github.io/pycco/
Other
845 stars 143 forks source link

Source code omitted if indentation level has no comment/docstring #41

Closed akaihola closed 13 years ago

akaihola commented 13 years ago

Consider this Python source snippet:

# Top-level comment
if True:
    class MyClass:
        def mymethod(self):
            if True:
                # Innermost comment
                print "Success"

When run through Pycco, this produces approximately:

nesting.py

Top-level comment     | if True:
                      |
Innermost comment     |                print "Success"

If I want the source code to be displayed correctly, I need to add either a comment or a docstring to every indentation level:

# Top-level comment
if True:
    class MyClass:
        """Docstring for MyClass"""
        def mymethod(self):
            """Docstring for mymethod"""
            # dummy comment for the if clause
            if True:
                # Innermost comment
                print "Success"

Maybe this is by design and is meant to encourage generous use of comments, but for me it feels cumbersome and is a blocker for using Pycco for larger existing codebases.

treyhunner commented 13 years ago

I'm not sure whether this is by design, but I have noticed this behavior as well. This behavior was introduced by bcb8f2c5f5a5adaee51eed9631e56ad7ebf557b5. Reverting that commit should fix the problem.

At the moment I consider this a bug, as this behavior was not in 0.2.0 and it forcibly hides any sections of code without commenting at every level.

treyhunner commented 13 years ago

Fixed by #35.