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

[임창진(callin) <callin2@...>]

Hi list
It looks great
Check it http://webpages.charter.net/edreamleo/front.html
It a kind of literate editor.
If you assume the coder and document writer are same person, it give
many idea to you.


2010년 11월 27일 토요일에 David Manura<dm.lua@math2.org>님이 작성:
> 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
>
>

-- 
임창진(rim.chang.jin)