[ANN] LuaAnnotate - C code comments externally stored but displayed inline / documenting Lua code

[David Manura <dm.lua@...>]

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.

Such a tool was first proposed by Steve Donovan [1].  The original
motivation for it 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.

An example source annotation file (annotations.txt) is provided for
the Lua 5.2.0-alpha sources.  It is far from complete, but patches to
it are welcome.

This is experimental to see if such a thing will be useful.  There is
probably prior art for such thing though perhaps not in this context.

[1] the recent "reducing patch complexity and conflicts" thread