Eric Knibbe avatar Eric Knibbe committed e1162c7 Draft

handle extra line breaks after description

Comments (0)

Files changed (1)

lasso/sphinxifier.lasso

   Given a set of Lasso files or element names, outputs reference docs for each
   element for the Lasso domain for Sphinx. Since Lasso defaults to not retaining
   docComments, prefix with `env LASSO9_RETAIN_COMMENTS=1` when running from the
-  command line. Generates reST markup like so:
+  command line. Generates reST markup like so (with extra line breaks):
 
   method:: signature
-    docstring                     <-- words from docComment before @attribute lines
+    docstring                     <-- docComment content before @-prefixed attribute lines
     :param name: description          <-- from "@param name description" in docComment
     :param type name: description     <-- type inserted if not ::any
     :param ...: description        <-- if signature has ... & docComment has @param rest or @param ...
   - Lasso has no way to show which member methods are public/protected/private (#7494)
   - a trait will see its requires disappear as imports are added (#7581)
   - data elements and therefore automatic getters/setters can't have docstrings
-  - doesn't detect redefinitions of existing methods or members
-
-  To-do:
-  - warn when finding @param lines with no matching parameter
-  - replace auto-collect with output to variable
-  - add line-wrapping to signatures and attribute descriptions
-  - add detection of members added to built-in types
-  - cut first line of description if it matches the name of the docComment's element
-  - onCreate methods should be listed first
+  - little error handling, e.g. when finding @param lines with no matching parameter
+  - uses auto-collect; might be faster with output to variable instead
 */
 
 not sys_getenv('LASSO9_RETAIN_COMMENTS') ?
 
     // fill params & others with data parsed from @attribute lines
     local(      // remove delimiters, trim & collapse whitespace but preserve paragraph breaks
-      components = #element->docComment->removeLeading('/**!')
+      components = #element->docComment->replace(regexp('^/\\*\\*!'),' ')
                                         &removeTrailing('*/')
                                         &removeTrailing('*')
                                         &replace(regexp('[ \\t]*(\\n|\\r\\n?)[ \\t]*'),'\n')
                                         &replace(regexp('[ \\t]+|(?<!\\n)\\n(?!\\n)'),' ')
-                                        &replace(regexp('^@'),' @') // needs leading space if no description
+                                        &replace(regexp('\\n+@'),' @') // first @ always needs leading space
                                         &split(' @')
     )   // array('description','param name Words about parameter','return Words about result')
     #components->first != null ? .'description' = #components->first->trim&;
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.