Lua Annotate

lua-users home

LuaAnnotate - C code comments externally stored but displayed inline.

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:

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].


See Also

RecentChanges · preferences
edit · history
Last edited November 27, 2010 1:34 am GMT (diff)