Re: [docbook-apps] documenting code

[Stefan Seefeld <seefeld@sympatico.ca>]

Dave Pawson wrote:
> Stefan Seefeld wrote:
>> Dave Pawson wrote:
>>> I've seen Norm using docbook to tangle and weave XML.
>>> I'm wondering how well docbook would work for code?
>>>
>>> I have a mixed bag of bash scripts, Python code and xslt.
>>> I want to keep it up to date and documented.
>>>
>>> I'm thinking about taking the working code (today)
>>> and embedding it in docbook.
>> I have never attempted to do anything like this with XSLT. C++, 
>> Python, etc. I usually handle the other way around: Instead of 
>> embedding the code into documentation, I embed documentation 
>> (comments) into the program, so I can extract it easily with special 
>> tools (I'm working on Synopsis: http://synopsis.fresco.org, which 
>> does that).
>
> 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.)

>> The advantage is that the code is readily usable without 
>> pre-processing, and the embedded docs are readable as mere code 
>> annotation. In particular, I prefer those documentation strings to 
>> use a lightweight markup (such as ReStructuredText: 
>> http://docutils.sourceforge.net/rst.html, which can be easily mapped 
>> to a subset of DocBook).
>
> I guess my overall goal is to document the code. I.e.
> cut up the code into small enough chunks to make
> documentation easy.
>
> 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.

(I also have DocBook formatters in Synopsis, so I can generate DocBook 
output from the above annotated source code, too.)



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.


Regards,
       Stefan

-- 

      ...ich hab' noch einen Koffer in Berlin...