Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Resolving Issue #4, fixing other bugs, updating docs

  • Loading branch information...
commit a0b9479022699a50eb9f2ec99906b8807f6acd54 1 parent 79e4282
@njlg njlg authored
Showing with 191 additions and 23 deletions.
  1. +38 −11 Default.sublime-keymap
  2. +87 −5 NaturalDocs.py
  3. +66 −7 README.md
View
49 Default.sublime-keymap
@@ -2,6 +2,8 @@
{ "keys": ["super+n"], "command": "natural_docs_insert_block" },
{ "keys": ["super+d"], "command": "natural_docs_decorate" },
{ "keys": ["super+g"], "command": "natural_docs_group" },
+
+ // insert the rest of the doc-block
{ "keys": ["enter"], "command": "natural_docs", "context" :
[
{ "key": "setting.auto_indent", "operator": "equal", "operand": true, "match_all": true },
@@ -41,6 +43,8 @@
{ "key": "preceding_text", "operator": "regex_contains", "operand": "^\\s*\\/\\*{2}$", "match_all": true }
]
},
+
+ // insert documentation punctuation on next line
{ "keys": ["enter"], "command": "insert_snippet", "args": {"contents": "\n${TM_CURRENT_LINE/^\\s*(\\*\\s*).*$/$1/}"}, "context":
[
{ "key": "setting.auto_indent", "operator": "equal", "operand": true, "match_all": true },
@@ -52,7 +56,7 @@
{ "keys": ["enter"], "command": "insert_snippet", "args": {"contents": "\n${TM_CURRENT_LINE/^\\s*(\\/\\/\\s*).*$/$1/}"}, "context":
[
{ "key": "setting.auto_indent", "operator": "equal", "operand": true, "match_all": true },
- { "key": "setting.natural_docs_continue_comments", "operator": "equal", "operand": true, "match_all": true},
+ { "key": "natural_docs_continue_comments", "operator": "equal", "operand": true, "match_all": true},
{ "key": "selector", "operator": "equal", "operand": "comment.line.double-slash", "match_all": true},
{ "key": "auto_complete_visible", "operator": "equal", "operand": false, "match_all": true },
{ "key": "preceding_text", "operator": "regex_contains", "operand": "^\\s*\\/\\/", "match_all": true}
@@ -61,7 +65,7 @@
{ "keys": ["enter"], "command": "insert_snippet", "args": {"contents": "\n${TM_CURRENT_LINE/^\\s*(#\\s*).*$/$1/}"}, "context":
[
{ "key": "setting.auto_indent", "operator": "equal", "operand": true, "match_all": true },
- { "key": "setting.natural_docs_continue_comments", "operator": "equal", "operand": true, "match_all": true},
+ { "key": "natural_docs_continue_comments", "operator": "equal", "operand": true, "match_all": true},
{ "key": "selector", "operator": "equal", "operand": " comment.line.number-sign", "match_all": true},
{ "key": "auto_complete_visible", "operator": "equal", "operand": false, "match_all": true },
{ "key": "preceding_text", "operator": "regex_contains", "operand": "^\\s*#", "match_all": true}
@@ -94,7 +98,7 @@
{ "keys": ["keypad_enter"], "command": "insert_snippet", "args": {"contents": "\n${TM_CURRENT_LINE/^\\s*(\\/\\/\\s*).*$/$1/}"}, "context":
[
{ "key": "setting.auto_indent", "operator": "equal", "operand": true, "match_all": true },
- { "key": "setting.natural_docs_continue_comments", "operator": "equal", "operand": true, "match_all": true},
+ { "key": "natural_docs_continue_comments", "operator": "equal", "operand": true, "match_all": true},
{ "key": "selector", "operator": "equal", "operand": "comment.line.double-slash", "match_all": true},
{ "key": "auto_complete_visible", "operator": "equal", "operand": false, "match_all": true },
{ "key": "preceding_text", "operator": "regex_contains", "operand": "^\\s*\\/\\/", "match_all": true}
@@ -103,29 +107,50 @@
{ "keys": ["keypad_enter"], "command": "insert_snippet", "args": {"contents": "\n${TM_CURRENT_LINE/^\\s*(#\\s*).*$/$1/}"}, "context":
[
{ "key": "setting.auto_indent", "operator": "equal", "operand": true, "match_all": true },
- { "key": "setting.natural_docs_continue_comments", "operator": "equal", "operand": true, "match_all": true},
+ { "key": "natural_docs_continue_comments", "operator": "equal", "operand": true, "match_all": true},
{ "key": "selector", "operator": "equal", "operand": "comment.line.number-sign", "match_all": true},
{ "key": "auto_complete_visible", "operator": "equal", "operand": false, "match_all": true },
{ "key": "preceding_text", "operator": "regex_contains", "operand": "^\\s*#", "match_all": true}
]
},
+ // deep indent on Enter
+ { "keys": ["enter"], "command": "natural_docs_deep_indent", "context":
+ [
+ { "key": "setting.auto_indent", "operator": "equal", "operand": true, "match_all": true },
+ { "key": "natural_docs_deep_indent", "operator": "equal", "operand": true, "match_all": true},
+ { "key": "selector", "operator": "equal", "operand": "comment.block.documentation", "match_all": true },
+ { "key": "preceding_text", "operator": "not_regex_contains", "operand": "^\\s*\\/\\*{2}$" },
+ { "key": "preceding_text", "operator": "not_regex_contains", "operand": "^\\s*=begin ND$" }
+ ]
+ },
+ { "keys": ["enter"], "command": "natural_docs_deep_indent", "context":
+ [
+ { "key": "setting.auto_indent", "operator": "equal", "operand": true, "match_all": true },
+ { "key": "natural_docs_deep_indent", "operator": "equal", "operand": true, "match_all": true},
+ { "key": "selector", "operator": "equal", "operand": "string.quoted.double.block.python", "match_all": true },
+ { "key": "preceding_text", "operator": "not_regex_contains", "operand": "^\\s*\"\"\"$", "match_all": true }
+ ]
+ },
+
// deep indent keymaps
{ "keys": ["tab"], "command": "natural_docs_indent", "context":
[
{ "key": "setting.auto_indent", "operator": "equal", "operand": true, "match_all": true },
- { "key": "setting.natural_docs_deep_indent", "operator": "equal", "operand": true, "match_all": true },
+ { "key": "natural_docs_deep_indent", "operator": "equal", "operand": true, "match_all": true },
{ "key": "selection_empty", "operator": "equal", "operand": true, "match_all": true },
- { "key": "selector", "operator": "equal", "operand": "comment.block.documentation", "match_all": true }
+ { "key": "selector", "operator": "equal", "operand": "comment.block.documentation", "match_all": true },
+ { "key": "has_next_field", "operator": "equal", "operand": false, "match_all": true }
]
},
- // deep ident for python
+ // (for python)
{ "keys": ["tab"], "command": "natural_docs_indent", "context":
[
{ "key": "setting.auto_indent", "operator": "equal", "operand": true, "match_all": true },
- { "key": "setting.natural_docs_deep_indent", "operator": "equal", "operand": true, "match_all": true },
+ { "key": "natural_docs_deep_indent", "operator": "equal", "operand": true, "match_all": true },
{ "key": "selection_empty", "operator": "equal", "operand": true, "match_all": true },
- { "key": "selector", "operator": "equal", "operand": "string.quoted.double.block.python", "match_all": true }
+ { "key": "selector", "operator": "equal", "operand": "string.quoted.double.block.python", "match_all": true },
+ { "key": "has_next_field", "operator": "equal", "operand": false, "match_all": true }
]
},
@@ -151,7 +176,8 @@
[
{ "key": "setting.auto_indent", "operator": "equal", "operand": true, "match_all": true },
{ "key": "selection_empty", "operator": "equal", "operand": true, "match_all": true },
- { "key": "preceding_text", "operator": "regex_contains", "operand": "^\\s*\\/\\*[^\\*\/]*$", "match_all": true }
+ { "key": "preceding_text", "operator": "regex_contains", "operand": "^\\s*\\/\\*[^\\*\/]*$", "match_all": true },
+ { "key": "natural_docs_deep_indent", "operator": "equal", "operand": false, "match_all": true }
]
},
{ "keys": ["enter"], "command": "insert_snippet", "args": {"contents": "\n${TM_CURRENT_LINE/^\\s*(\\*\\s*).*$/$1/}"}, "context":
@@ -159,7 +185,8 @@
{ "key": "setting.auto_indent", "operator": "equal", "operand": true, "match_all": true },
{ "key": "selector", "operator": "equal", "operand": "comment.block", "match_all": true},
{ "key": "auto_complete_visible", "operator": "equal", "operand": false, "match_all": true },
- { "key": "preceding_text", "operator": "regex_contains", "operand": "^\\s*\\*", "match_all": true }
+ { "key": "preceding_text", "operator": "regex_contains", "operand": "^\\s*\\*", "match_all": true },
+ { "key": "natural_docs_deep_indent", "operator": "equal", "operand": false, "match_all": true }
]
}
]
View
92 NaturalDocs.py
@@ -56,6 +56,35 @@ def get_parser(view):
return module.Parser(preferences)
+class NaturalDocsListener(sublime_plugin.EventListener):
+ """
+ Class: NaturalDocsListener
+
+ This is used to return NaturalDocs settings to keymaps
+
+ Extends: sublime_plugin.EventListener
+ """
+
+ def on_query_context(self, view, key, operator, operand, match_all):
+ if key == "natural_docs_continue_comments":
+ settings = sublime.load_settings('NaturalDocs.sublime-settings')
+ if operator == sublime.OP_EQUAL:
+ return operand == settings.get('natural_docs_continue_comments')
+
+ if operator == sublime.OP_NOT_EQUAL:
+ return operand != settings.get('natural_docs_continue_comments')
+
+ elif key == "natural_docs_deep_indent":
+ settings = sublime.load_settings('NaturalDocs.sublime-settings')
+ if operator == sublime.OP_EQUAL:
+ return operand == settings.get('natural_docs_deep_indent')
+
+ if operator == sublime.OP_NOT_EQUAL:
+ return operand != settings.get('natural_docs_deep_indent')
+
+ return None
+
+
class NaturalDocsCommand(sublime_plugin.TextCommand):
def run(self, edit, definition='', inline=False):
@@ -101,7 +130,16 @@ def run(self, edit, definition='', inline=False):
write(v, first)
first = prefix
- if not definition:
+ # Find the line that we need to insert documentation for
+ if not definition and parser.insert_after_def:
+ # read the line before we inserted the doc block
+ point = v.sel()[0].end()
+ line_region = v.line(point)
+ line_region = v.line(line_region.begin() - 1)
+ line_region = v.line(line_region.begin() - 1)
+ line = read_line(v, line_region.begin())
+
+ elif not definition:
# read the line after we inserted the doc block
point = v.sel()[0].end()
line = read_line(v, point + 1)
@@ -162,7 +200,7 @@ def swapTabs(m):
write(v, "$0" + end)
-class NaturalDocsInsertBlock(sublime_plugin.TextCommand):
+class NaturalDocsInsertBlockCommand(sublime_plugin.TextCommand):
"""
This tries to start a Doc Block where one does not already exist
"""
@@ -176,6 +214,8 @@ def run(self, edit):
point = v.sel()[0].begin()
line_point = v.full_line(point)
current_line = v.substr(line_point)
+ next_point = v.full_line(line_point.end())
+ next_line = v.substr(next_point)
if len(current_line.strip()) > 0:
# cursor is on the function definition
@@ -183,9 +223,15 @@ def run(self, edit):
# position the cursor inside the function
v.run_command("move", {"by": "lines", "forward": True})
v.run_command("move_to", {"to": "bol", "extend": False})
- v.run_command("insert", {"characters": "\n"})
- v.run_command("move", {"by": "lines", "forward": False})
- # should we verify tabs are correct???
+
+ if len(next_line.strip()) > 0:
+ # move next line down
+ v.run_command("insert", {"characters": "\n"})
+ v.run_command("move", {"by": "lines", "forward": False})
+ else:
+ # insert whitespace
+ v.run_command("reindent")
+
else:
# move the function down to begin our block
v.run_command("move_to", {"to": "bol", "extend": False})
@@ -197,6 +243,11 @@ def run(self, edit):
point = v.sel()[0].end() - (col + 1)
line_point = v.full_line(point)
current_line = v.substr(line_point)
+
+ # alignment
+ v.run_command("reindent")
+
+
else:
point = v.sel()[0].end() + 1
line_point = v.full_line(point)
@@ -228,6 +279,37 @@ def run(self, edit):
v.insert(edit, current_position, " ")
+class NaturalDocsDeepIndentCommand(sublime_plugin.TextCommand):
+
+ def run(self, edit):
+ v = self.view
+ parser = get_parser(v)
+
+ re_block_middle = re.escape(parser.block_middle.strip())
+
+ current_position = v.sel()[0].begin()
+ current_line = v.substr(v.line(current_position))
+ matches = re.match('(?P<whitespace>\s+)' + re_block_middle + '(?P<else>.+) - ', current_line)
+
+ insert = "\n" + parser.block_middle
+ if matches is not None:
+ # Align next line based on hyphen
+
+ length = len(matches.group('else'))
+ length += 3
+ insert = "\n" + matches.group('whitespace') + parser.block_middle.strip() + (' ' * length)
+
+ else:
+ # Align net line based on beginning of last line
+ matches = re.match('(?P<whitespace>\s+)' + re_block_middle + '(?P<else>\s*)', current_line)
+
+ if matches is not None:
+ length = len(matches.group('else'))
+ insert = "\n" + matches.group('whitespace') + parser.block_middle.strip() + (' ' * length)
+
+ v.insert(edit, current_position, insert)
+
+
class NaturalDocsJoinCommand(sublime_plugin.TextCommand):
def run(self, edit):
View
73 README.md
@@ -355,7 +355,9 @@ def test_test(one, two=12, three='something'):
## natural_docs_deep_indent
-If this is set to `True` then pressing `Tab` inside a documentation block, will try to add enough spaces to align the cursor below the description section of the previous line (which only the Parameters section has), otherwise it will just insert two spaces.
+This setting controls whether to align lines inside documentation blocks based on the previous line.
+
+When using `Enter` inside a documentation block, NaturalDocs will try to align the start of the next line either (1) after the parameter dash (space-hyphen-space) or (2) at the first actual start of last line. See examples.
Example:
@@ -364,12 +366,64 @@ Example:
* ...
* Parameters:
*
+ * one - this parameter does something |
+ * twoLong - string
+ */
+```
+
+If the current line that contains ' - ', then pressing `Enter` will insert enough spaces to align the cursor under the description of the previous line. Result:
+
+```javascript
+ /**
+ * ...
+ * Parameters:
+ *
+ * one - this parameter does something
+ * |
+ * twoLong - string
+ */
+```
+
+Similarly, if the current line does not contain ' - ', then pressing `Enter` will insert enough spaces to start the line under the first non-Whitespace character inside the documentation. Starting at:
+
+```javascript
+ /**
+ * ...
+ * Parameters:
+ *
+ * one - this parameter does something
+ * this is another line |
+ * twoLong - string
+ */
+```
+
+Results in:
+
+```javascript
+ /**
+ * ...
+ * Parameters:
+ *
+ * one - this parameter does something
+ * this is another line
+ * |
+ * twoLong - string
+ */
+```
+
+If this setting is enabled, and there are no snippet fields available in the documentation block, you can also use `Tab` to insert as many spaces as necessary to put the cursor below the description of the previous line.
+
+```javascript
+ /**
+ * ...
+ * Parameters:
+ *
* one - this parameter does something
- * |
+ * |
*/
```
-If the cursor is below a line that contains ' - ', then pressing `Tab` will insert enough spaces to align the cursor under the description of the prvious line. Result:
+Pressing `Tab` results in:
```javascript
/**
@@ -381,7 +435,6 @@ If the cursor is below a line that contains ' - ', then pressing `Tab` will inse
*/
```
-
## natural_docs_continue_comments
If this setting is set to `True`, then pressing `Enter` on a line with a double-slash or number-sign comment will place that comment punctuation at the beginning of the next line.
@@ -503,18 +556,24 @@ If set to `false`, the normal comment tag will be used. Example:
# Changelog
+## July 9, 2012
+
+* Fixed bug with documenting the wrong line if language likes commends below the thing to be documented (e.g. Python)
+* Added a custom EventListener to check NaturalDocs settings from keymap contexts
+* Resolved [Issue #4](https://github.com/SublimeText/NaturalDocs/issues/4): `Tab` was overriding `next_field` actions.
+
## June 29, 2012
-* Resolved Issue #6: inserting doc-blocks does not work when directly above EOF
+* Resolved [Issue #6](https://github.com/SublimeText/NaturalDocs/issues/6): inserting doc-blocks does not work when directly above EOF
* Fixed bug with new preferences file not getting used correctly all the time (especially for non-Javascript like languages)
## June 11, 2012
-* Resolved Issue #5: Move settings file to `NaturalDocs.sublime-settings` / `User/NaturalDocs.sublime-settings`
+* Resolved [Issue #5](https://github.com/SublimeText/NaturalDocs/issues/5): Move settings file to `NaturalDocs.sublime-settings` / `User/NaturalDocs.sublime-settings`
## May 15, 2012
-* Fixed Issue #3 : inserting doc-blocks does not work when directly above EOF
+* Fixed [Issue #3](https://github.com/SublimeText/NaturalDocs/issues/3): inserting doc-blocks does not work when directly above EOF
* Fix bug with inserting a Group block when parser uses
* Changed default keymappings for OSX
Please sign in to comment.
Something went wrong with that request. Please try again.