Re: [docbook-apps] documenting code

[Dave Pawson <davep@dpawson.co.uk>]

Stefan Seefeld wrote:
>> But XSLT can already do that Stefan?
> As I mentioned, for me, being a developer, the documentation is embedded 
> into the code, not the other way around. Thus, the file to be processed 
> is primarily a source file that can readily be compiled / interpreted, 
> while documentation is embedded as annotation that may be extracted. 
> (This extraction is even part of the language / runtime in case of 
> Python, but not in other languages such as C++ or Java.)

OK, just a different approach.



>> http://www.dpawson.co.uk/temp/genWrapper.sh.html shows the start
>> of an example.
>>
>> Have you any examples to compare Stefan?
> Any piece of java code with embedded javadoc comments, for example. Here 
> is some C++ code, with embedded documentation, and cross-referenced via 
> Synopsis: http://synopsis.fresco.org/sxr/Source/src/Synopsis/Buffer.hh.html
> The respective documentation is here: 
> http://synopsis.fresco.org/docs/Manual/cxx/index.html.

OK, quite a different approach and usage.

> Note that this is not quite the same level of literate programming as 
> you seem to aim for, 

Yes,

> as I only document language artifacts themselves, 
> i.e. variables, types, functions, etc., while you want to annotate 
> individual statements.


Or indeed anything from a complete shell script down to commenting
on individual lines.


Thanks Stefan.


regards

-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk