Formatting multiline comments in source code (also for documentation)?
1
vote
0
answers
411
views
What I'm looking for can be stated simply as:
Are there any existing tools/approaches, that would allow me to (at least partially) automatically format C source code comments for documentation?
I'm primarily interested in handling C comments, but if there is a tool that is language agnostic, even better.
I should note that I do not use IDEs, mostly GUI text editors like Scite or Geany (I find
" class="img-fluid rounded" style="max-width: 100%; height: auto; margin: 10px 0;" loading="lazy">
So, it only works when typing "new", it cannot really figure out line breaking if there is text in front of the cursor, and as noted in the [SO post](https://stackoverflow.com/questions/3299699/reformatting-text-or-better-latex-in-80-colums-in-scite/15852969#15852969) :
> ... it inserts linebreaks upon typing text - but not on pressing backspace, nor upon copy/pasting.
... and obviously, it doesn't "know" what a C multiline
Something like that in a command line tool, that can accept a line of text which is a function signature, and generate skeleton for a documentation, appropriate for example for [Doxygen](https://www.doxygen.nl/manual/starting.html) (or if text with both documentation comments and function signature is supplied, existing text in comment is left, and any new parameters of the function signatures are inserted), would be awesome - is there something that works like that? I had a hard time finding something like that, probably because it is not trivial to do: the tool would not only have to be "multiline-comment aware", but also "programming-language aware".
I thought one possibility for such command line tools are source code "pretty print" formatters, but I've used [Artistic Style (astyle))](https://astyle.sourceforge.net/) before, and as far as I can remember, it usually leaves comments as they are. However, I've found this formatter, where a similar idea has been discussed in [Wrap comments · Issue #265 · prettier/prettier · GitHub](https://github.com/prettier/prettier/issues/265) - however, it seems it is not implemented yet there; though there is the screenshot of a demo of a plugin for Atom text editor (click for full-size animated gif):
" class="img-fluid rounded" style="max-width: 100%; height: auto; margin: 10px 0;" loading="lazy">
As far as I can see, this is just automatic line break, then when the formatting goes off, the plugin is called to replace the text of the comment - and it is even aware when several lines of single line comments forms a block.
So one option for me would be to use Atom with [format-javascript-comment](https://github.com/amannn/atom-format-javascript-comment) plugin to format C comments, except I've tried Atom, and I found it kinda overwhelming (almost felt like an IDE). Which is why I would prefer the plugin's functionality in a stand-alone command line tool.
So, is there a command line tool, that -- even if incapable of generating documentation skeletons, -- is capable of accepting text input; identifying blocks of either several single-line comments, or blocks of multi-line comments; formatting them up to a character width (allowing for customization of how existing indentation in comments is handled); and then outputting the newly formatted text?
vim
/emacs
too difficult unfortunately); so I'm looking for either a standalone command-line tool (or say a Python library that does all the heavy lifting, and allows for a pretty trivial executable script that would function as a command-line tool) -- or a plugin for a GUI text editor (or a relatively simple GUI text editor), that can perform such formatting.
-----
Let me expand on this with a few examples.
Ideally, I'd like this to be a mode in a text editor, such that: if you're within a multiline C /* ... */
comments, then as you type, lines get broken at required width (80 characters), and new lines within the comment automatically get *
appended at start.
For Scite, there is a http://lua-users.org/wiki/SciteLineBreak extension, and it works somewhat like this (click for full-size animated gif):

/* ... */
comment is.
So, a GUI text editor functionality like that, which is "live" and "multiline-comment aware", can insert/delete *
on start of line, and can handle copy/pasting, backspace, and text in front of the cursor, would be truly awesome. Is there anything out there that can work like this?
-----
On the other hand, there is the "command line" type of interaction, where the command line tool receives text input, and returns formatted text output. In text editors, say Scite, it would then be easy to make a Lua script addon to call this tool with the input being the selected text, and then replace the text selection with the output.
In the Windows/Visual Studio world, there is a paid addon called [Atomineer Pro Documentation for Visual Studio](https://www.atomineerutils.com/) (found via [What is the best tool or technique to write doxygen code comments - Stack Overflow](https://stackoverflow.com/questions/1211944/what-is-the-best-tool-or-technique-to-write-doxygen-code-comments)) , which can create a skeleton for a documentation comment from a function signature, upon pressing the keyboard shortcut CTRL+SHIFT+D:
[] 

Asked by sdbbs
(578 rep)
Dec 30, 2022, 02:11 PM