Updated 2014-04-26 20:18:34 by pooryorick

MAKR 2004-11-18:

I noticed - and came across the same problem - people on comp.lang.tcl are regularly asking for tools to automatically generate documentation from source code. It seems no page is currently dedicated to maintain a list of tools available for Tcl.

See Also  edit

Literate Programming
another approach to document generation, where the documentation is the primary content, and the program must be extracted from it. Not as popular as document extraction, but advocated by Donald Knuth.
Tcl Style Guide
Contains a couple of recommendations about documentation near the end of the page.
GSoC Idea: Auto Documentation Tool for Tcl
a 2011 project proposal in this direction
docbook
However, I'm uncertain how much use of docbook occurs in the tcl development community efforts to document tcl.

Documentation Extraction  edit

The following systems operate by extracting documentation from comments in the program code
autodoc
ddoc
docextract
extracting doctools text from source files
docstring
using leading comment in proc bodies
docstrip
docstrip and tclldoc
Literate programming the scripting way
doctools
this is more a generic markup language tool
doxygen
documentation tool; has tcl support starting with version 1.7.5 (see doxygen+tcl) and can be used for tcl with a filter/pre-processor [1] [2] A little doxygen converter
HelpSystem
interactive help doc embedded into tcl/tk code - kind of different
robodoc
Ruff!
generates documentation via runtime introspection
Sdoc
Simpledoc
very simple: generates HTML from source with markup in comments.
src2tex
tcl2tex
tcldoc
similar to javadoc
tdoc
TL
this is a glue language that has auto documentation functions
TMML
this is more a generic markup language tool
tna
tycho
this GUI itcl dev environment included a system to create HTML from itcl classes
zdoc
feathers: an hand-written documents tool
NaturalDocs
attempts to parse code docs written in a very natural manner
XOTcl Documentation Tool

Development Tools  edit

ParseTools
extension that can be used to write documentation extractors

Discussion  edit


escargo 2005-04-21: One thing to keep in mind with these tools is that some of them might be used with OO systems that extend the Tcl syntax, Snit for example. Now, instead of just need to track proc definitions, namespaces, and global variables, you might want to keep track of classes, methods, typemethods, and other interesting extended Tcl syntax. I haven't looked at all of these tools, but I know that robodoc made it possible to handle pretty arbitrary things to track and document.

MAKR 2006-12-08: Half a year ago I decided to move over to robodoc. I now have all in-source documentation (C and Tcl) converted to this format. This was one of the best ideas I ever had. The commentary in the sources is clean and readable. The resulting HTML documentation is it too. You can format it to your liking using CSS...

escargo: Do you use any OO extensions, or just plain Tcl/Tk?

MAKR 2006-12-13: As it gets tool specific, I continue at the robodoc page ...

MAKR 2007-12-14: just stumbled over discussions about the Tcl user documentation project and also saw an What you need to know to write man pages, by Peter Seebach, 2004-02-10, at c.l.t. about how to write manpages.

Lorance: Since I have used Perl POD for years I decided I Should use that for Tcl. I have added embedded POD support to my personal tcl.vim syntax file. See my Github Repository for more information (The Wiki has screenshots).