OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook-apps] documenting code

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, 


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


Dave Pawson

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]