natural_docs_deep_indent:true defeats tabbing between snippet sections

[joelpt]

When natural_docs_deep_indent is set to true, pressing Tab prevents tabbing between snippet sections (e.g. jumping from description to each parameter to the return value).

I have given this some thought and I'm currently thinking that the following approach would be pretty ideal:

• If below a line with '-' in it, when Enter is pressed, automatically align cursor below description from above line
• If below a line without '-' in it, when Enter is pressed, automatically align cursor below first non-whitespace of above line
• When Tab is pressed, if we have already tabbed through all the snippet sections in the current comment block, then just insert a tab character (or equivalent whitespace per Sublime's settings); otherwise jump to the next snippet section

I think this is sort of a "best of both worlds" approach, and perhaps would make the natural_docs_deep_indent option obsolete; just always behave in the manner described above and for the most part it should do what the user would intuitively want.

I think it's unlikely that (during the initial snippet-section-tabbing phase) a user would not want to be aligned under the above description-block when they press Enter; such behavior is probably always desirable.

This would in turn free the Tab key to be used exclusively for tabbing through the snippet sections, until the user has "filled out" all the snippet sections. Once that has happened, pressing Enter below any block-indented line should still do the automatic alignment thing, and pressing Tab should insert a tab or equivalent whitespace. I think having Tab use this behavior would be more useful in general as it would make for easier alignment of text in descriptions that needs to be in a tabular format (e.g. sub-comments aligned to the right in an example block of code).

Currently I am running with natural_docs_deep_indent set to true because the alignment behavior is just so sweet, but I do miss the section-jumping functionality that this currently inhibits.

[joelpt]

To support the case where the user wants to insert additional non-aligned lines of text in e.g. the Parameters block, I suggest making Ctrl-Enter do so, and otherwise let Enter always perform the alignment function that Tab currently performs when natural_docs_deep_indent is true.

[njlg]

I like your idea. It makes a lot of sense. Let me look into doing that. (Feel free to submit a patch) I really only used the feature after I had tab'd through everything and then went back to fill in more details.

[njlg]

Long time in the making: After you update let me know what you think. Basically this setting now works like this:

• Tab only works if there are no snippet fields.
• Enter inside a documentation block should always try to align the next line based on the current line.

The readme has been updated with examples of these two.

[joelpt]

Oh this is nice. Works lovely. Thanks very much!