I created fdoc (which is pretty print format woven directly by the felix webserver) to write the Felix tutorial (since interscript got chucked out).
Now I'm finding: * the code in the tutorial can't be checked by compiling/running it * I want libraries to be "self-documenting" somehow so I can just point the browser at them, or at least a wrapper. It's easy to insert a while library file into a fdoc document: @felix filename but there's no way to add commentary in the middle of the file. OTOH if we put the whole description in the library for beginners it makes the code too cluttered to use as a reference, once you know how it works. Comments in the code just don't cut it. The "publish" syntax was a nice idea but doesn't really work nicely either. Now: with a "cluttered" source the webserver can easily have a "declutter" button to get rid of the verbose descriptions, but the text file would still be hard to edit. It's also hard to document interfaces in Felix because they don't stand out easily from definitions, that is, you really need the felix parser to split them up: a dumb tool like the webserver can't do it. I'm looking for ideas here! One is to add tags into the code: //@tagname and allow to interleave fdoc descriptions and the code. The tags clutter the code, but not too much perhaps? Of course keeping the docs in sync is still a problem. -- john skaller skal...@users.sourceforge.net ------------------------------------------------------------------------------ RSA(R) Conference 2012 Mar 27 - Feb 2 Save $400 by Jan. 27 Register now! http://p.sf.net/sfu/rsa-sfdev2dev2 _______________________________________________ Felix-language mailing list Felix-language@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/felix-language
