search

microsoft / pylance-release

Documentation and issues for Pylance
Creative Commons Attribution 4.0 International
1.71k stars 765 forks source link

Add a "fold all docstrings" command #4677

Open rchiodo opened 1 year ago

rchiodo commented 1 year ago

Discussed in https://github.com/microsoft/pylance-release/discussions/3933

Originally posted by **jonasreiher** December 8, 2022 Docstrings covering all input parameters, types and precise function/class descriptions can become quite long and get in the way of the actual code. Usually, you only need to look into them when writing them or when looking up a specific function/class and it would be preferable to have them folded most of the time. You can do this by clicking the arrow next to the line numbers for each of them. This becomes tedious for files with a lot of docstrings, though. There exists the "fold all block comments" command in VS Code but docstrings are not considered as block comments since they have the same format as multi-line strings and you wouldn't want to fold them away (see microsoft/vscode-python#20330). **Proposal: a "fold all docstrings" command that, well, folds all docstrings**, so multi-line strings that are the first item in a function/class definition. **Alternative proposal: classify all multi-line strings as block comments that are are not inside of a function call or variable assignment**. This would be consistent with the "toggle block comment" command that wraps the selection in triple quotes. Creating a _block comment_ like this but then not being able to fold it with "fold all _block comments_" seems contradictory.
rchiodo commented 1 year ago

Thought this might be a good thing to do in the near future.

excubo-jg commented 1 year ago

Good to see that this nuisance is getting tackled. Here is a similar request from me in PTVS - it would be good if the solution were applicable in VS, too.

https://github.com/microsoft/PTVS/discussions/7412

rchiodo commented 1 year ago

Unfortunately, I believe PTVS would have to be done separately. The same commands don't apply to Visual Studio.

starball5 commented 1 year ago

Historically related: microsoft/vscode-python#20330

Related on Stack Overflow: The "Fold All Block Comments" command doesn't work on Python docstrings in files with certain arrangements of import, where it was also discovered that interestingly, the Fold All Block Comments command does actually affect docstrings, but only under certain conditions which are not precisely known by me or the asker of that question. Not sure if that's intended or not.

winoo19 commented 2 weeks ago

I made a vscode extension to tackle this exact problem, as it was bugging me so much: https://marketplace.visualstudio.com/items?itemName=DanielSanchez.docstring-fold-and-unfold