automatic code examples in documentation

[Gerrit Wichert]

This is a post i made deep in the 'improving the join function' thread.
Steven asked me to open a new thread on it, so here it comes.
 

Am 13.10.2010 22:07, schrieb Andrei Alexandrescu:

> >
> > Good point. On the other hand, an overly simplified documentation
> > might hinder a good deal of legit uses for advanced users. I wonder
> > how to please everyone.
>   
I think the best way to explain the usage of a feature are *working* code-examples.
Maybe it's possible to have a special unit-test block named such as 'example'.
The compiler can completely ignore such sections or just syntax check them, or ... .

For doc generation they are just taken as they are and put into (or linked to) the documentation.

It may be even possible for the doc generator to compile and run these samples, so they become some kind of unit test and their possible output
can be part of the documentation.

Just an idea that comes to my mind



This was the original post, now some more explanation:

How can the syntax look like ?


... library code

@documentation( code) {
  //hello world example code
  import std.stdio;
  void main() {
     writeln( "Hello, world!");	
  }
}

more library code ...

This is how a simple example code section may look like.
The @documentation annotation tells the compiler not to generate any code
from the section. The minimal thing it has to do is generate a string from
the section content and forward it to the document-generator.
This should be sufficient for easily getting code examples into the documentation.

I think its a good idea if the compiler executes a syntax check on the example section,
like it does on the already implemented syntax checked strings.

Then the compiler part is done with this. This are code examples, not unit tests.
They are not run with the other unit tests. 
I think code examples are most usefull if they are self-contained little programs.

Part of the document generation may be to compile and run the extracted examples.
When a example does't compile it can be marked as defunct or excluded from the 
documentation. The doc-generator can catch the output of the running examples 
and add it to the documentation as result.

Shurely there are some problems when trying to compile the examples like wich 
libs to link with, or what about GUI-code, or just code snippets, but for me 
this is all secondary, maybe we can make that work later. The most important part 
is to define the transfer mechanics to get the example code into the documentation.
 
So what do you think?

 
Gerrit

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20101015/7eee7456/attachment-0001.html>