Lua Annotate

wiki

LuaAnnotate is a tool for displaying C source file comments inline to the source but stored in a separate file. The comments are maintained in a text file ([annotate.txt]) in the same directory as the C sources. Displaying the comments inline to the C code can be done in many ways:

• weaving the comments into the source code as C comments and saving the result to a temporary file for viewing in any text editor.
• displaying comments as annotations in the SciTE text editor when viewing the original source files (without altering those source files).
• other possibilities (not implemented) include rendering as HTML or creating plugins for other text editors.

The original motivation for this project is to allow Lua users to better document the Lua source code. The Lua source code is dense but sparsely commented. It's uncertain whether the original Lua authors will incorporate generous use of comments in the original upstream sources, so we need to maintain the comments separately. This becomes challenging when the upstream sources change and users themselves may maintain their own set of patches. The problem with using unified patches here is that the contextual information contained is more detailed than necessary and its conflict checking is more strict than necessary. All the comment data really needs to say is that a certain identifier corresponds with a certain piece of documentation, almost in the manner of ctags. Furthermore, if such an identifier cannot be matched in the source, we don't care that much --it's just documentation.

Example (viewing lobject.h):

For further details and to download, see [lua-annotate on github].

--DavidManura

See Also

• LuaSource