Fold multiline docstrings.

[YorikSar]

Implementation is not strict but works fine.

[tmhedberg]

Thanks for your contribution!

Just a few comments:

• This would fold not only multi-line docstrings, but any multi-line string. Is that intentional?
• Multi-line strings can be delimited by ''' as well as """, but your regular expressions only cover the latter case.
• There are a multitude of Python syntactic constructs which we could fold (conditionals, loops, line continuations, multi-line dictionaries and lists, etc.), but thus far, I have deliberately chosen to only fold class and function definitions, in order to keep the plugin as small and simple as possible and cover only the cases which for which I feel folding is more or less universally desirable. I'm not sure that multi-line string/docstring folding would also fall into that category, but I'm open to being convinced. Perhaps it could be added as an opt-in feature instead of being enabled automatically?

[YorikSar]

Hello. Thanks for swift response.

• Yes, it is. Maybe it's me, but I usually meet multiline strings either in docstring or in some "Usage" for CLI. So they are almost the same.
• Oops. Was trying to make it work first. I'll add this.
• I'll try to convince you below.

The first line of a docstring is usually a very short definition of what the method/class/module do. So if we fold it, we would hide only detailed explanation keeping the necessary information visible. Well-written docstrings for classes are of the same size or even bigger than methods in it. So if we have foldlevel=1 (as I set it in .vimrc), we'll see classes with huge docstrings and short list of methods. I think, the point of folding is to get as much high-level information on the screen as possible with as less scrolling as possible. That's exactly what we get when we fold these docstrings: class, short info on what it does, list of it's methods.

Well, of course we can hide this behind an option. But isn't "no configuration needed" a cool thing? :)

[tmhedberg]

OK, that sounds reasonable to me. If you can just fix up the single/double quotes issue, I'll merge it.

I agree that zero configuration is good, but flexible configuration with well-chosen defaults is even better, in my opinion. That said, I think it will be fine to have this enabled by default, though I may add an option to disable it at some point.

[reckoner]

What about folding long doctests in the multiline docstring as well as a separate embedded fold?

[YorikSar]

@reckoner
What do you mean by "embedded fold"?

[reckoner]

Something like:

def foo(x)
    '''
    this is doc

    >>> here is test
    >>> more test
    '''
    print 'some statements in foo'

folds like

    ------ def foo ------

and then unfolds to

    def foo(x):
    ------- ''' ---------
    print 'some statements in foo'

and then unfolds again to

    def foo(x):
    '''
    this is doc
    ------- >>> ---------
    '''
    print 'some statements in foo'

and then unfolds again to

    def foo(x):
    '''
    this is doc
    >>> here is test
    >>> more test
    '''
    print 'some statements in foo'

I hope that helps.

[tmhedberg]

@YorikSar I apologize for taking so long to merge this. I missed the second commit you added and forgot to come back and check on this ticket until today. Anyway, it's merged now. Thanks again for contributing.

@reckoner:

I see the utility in your suggestion, but I feel that it probably exceeds the upper threshold of complexity that I'd like to include in this plugin. As I mentioned in an earlier comment, there are a lot of things that we could fold in Python code, but which I have deliberately chosen not to in order to keep the plugin simple.

I am open to discussing it further, but I'd suggest opening a separate issue for that, so that we can consider this one closed.

[YorikSar]

@tmhedberg, no worries. I just realized that GH doesn't send notifications on new commits for pull requests myself.

[scanny]

Hi @tmhedberg, I'm one of folks who would prefer to keep this turned off most of the time. My docstrings are usually just a few lines long and I prefer the simpler "see it all or don't see it at all" behavior for methods and classes. Is there a configuration variable I can use to turn off the folding of docstrings?

[tmhedberg]

No, I've never gotten around to adding that option. For personal reasons, I probably won't be able to work on this in the very near future, but this should be a pretty simple feature to add, and I'd welcome a patch for it, if you're so inclined.

[scanny]

Sure Taylor, let me take a look and see if I can work it out. I'm an experienced programmer, but haven't written any Vimscript yet. I've been dipping in and out of Steve Losh's text on it though so this will make a good exercise :)