[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 ** [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 E. Knuth%|%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. ** Tools ** [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]: A more generic [markup language] tool. Targets multiple presentation formats. [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 [http://therowes.net/~greg/software/tcl-doxygen-filter/tcl-dox-0.6.tar.gz] [http://therowes.net/~greg/download/tcl-doxygen-filter/] [A little doxygen converter] [HelpSystem]: interactive help doc embedded into tcl/tk code - kind of different [mkdoc::mkdoc]: Embed code documentation in Markdown into programming languages like Perl, R, Tcl, Python or C++. Singe file command line application or can be used as Tcl package [robodoc]: [Ruff!]: generates documentation via runtime introspection [Sdoc]: * nroff man macro style - by far the most common. Requires some kind of tool to either format or to convert into another form [https://github.com/fgpietersz/simpledoc%|%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 ** [ParseTools]: extension that can be used to write documentation extractors ** Discussion ** [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, [namespace]s, and [global] variables, you might want to keep track of classes, [method]s, 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 [http://www.linux.com/articles/34212%|%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 https://github.com/LStinson/Vim%|% Github Repository%|% for more information (The Wiki has screenshots). ---- '''[MHo] - 2020-11-16 22:32:49''' IMHO This page is a good example for the situation of Tcl/Tk: Where other languages or eco systems have only one, or sometimes two or three solutions, the tcl community offers 50. But to decide which one you should use, you often spend a whole evening, looking sometimes at 404's, at "no longer maintained"-Messages, or at something like "only works under this and that circumstances...", "work in progress", etc. Not that I am misunderstood: after "studying" a lot of languages I still vote Tcl/Tk as one of the best, if not Nr One. Simplicity and flexibility is unbeaten, deployment via starkits and starpacks as simple and mighty as it can be all together, robustness is great, errors are rare, performance very good in many scenarios. But, what the hell, why isn't this ingenious language more popular after all? <> Documentation