charlesdaniels / shelldoc Goto Github PK

See commit d66c7ba

The new --prefix feature cannot be adequately tested within the framework of do_test.sh. I would propose adding an additional script to test this feature individually. In any case, it needs proper smoke testing.

Example:

... some code ...
# .INLINE

Some documentation which is directly pertinent to this code, but which also needs to wind up in the generated reST
# .ENDOC
... more code ...

The trouble lies in how exactly to handle .INLINE type blocks, since if we wanted to just append the text to the top-level .SCRIPTDOC segment, we would have to buffer the .SCRIPTDOC segment in memory until EOF is reached.

Alternatively, .INLINE segments could be accumulated, concatenated, and added to the output after EOF is reached, and thus displayed under a section header along the lines of "Further Notes".

This is the closest thing we have for of a convention for shell code comments. It would be cool if the parser could understand the syntax:

https://google.github.io/styleguide/shellguide.html#s4-comments