Stata The Stata listserver
[Date Prev][Date Next][Thread Prev][Thread Next][Date index][Thread index]

RE: st: RE: automatic documentation for Stata ?

Subject   RE: st: RE: automatic documentation for Stata ?
Date   Mon, 10 May 2004 12:27:01 +0200

Good morning,

It is feasible. And fairly easy with Stata's -file- command and string 
functions. But you will have to define your own standards for adding "meta 
information" to the ADO files (or borrow it from other languages -eg. 
javadoc as you mention), and it is unlikely that you will find 
user-written solutions that exactly fit what you want. 

Adrian Mander's package -makehlp.ado- might be a very good starting point 
though (findit makehlp returns a download site).

I recently did something similar too. My objective was to create a tool to 
avoid the (painstaking IMHO) task of writing SMCL help files --very much 
like the -makehlp- package--. Note that, rather than adding "meta data" in 
the ADO files (as you suggest), I found it more flexible to define a 
simple standard for a "Stata package description sheet": that is simply a 
structured text file containing the material needed to create a 
SMCL-formatted help file: title, description, date, syntax description, 
author(s) name, etc. Then I wrote a parser (a Stata command) that reads 
the "description sheet" file and generates the SMCL-help file (and other 
things such as LaTeX-formatted doc). The most useful feature to this is 
the direct translation of "syntax ..." statements, grabbed from the ADO 

I wrote the parser in Stata (using -file-), but as Nick Cox rightly 
pointed out, it is certainly easier to write such a script in, say, AWK, 
or some other scripting language well-equipped for parsing text files. 
Yet, I preferred to keep everything in the same environment. 

However, please, don't ask for the files! It is still pre-beta, 
under-documented, (likely) bugged, and not robust, so I do not want to 
share it (yet). Time permitting, I will certainly tidy it a bit and make 
it suitable for distribution some day...

Hope this helps


Philippe Van Kerm
  Integrated Research Infrastructure 
           in the Socio-economic Sciences (IRISS)
  BP48, L-4501 Differdange
  G.-D. Luxembourg
  RePEc profile:

st: RE: automatic documentation for Stata ?

  "Nick Cox" <>
  st: RE: automatic documentation for Stata ?
  Fri, 7 May 2004 13:52:23 +0100

I'm not familiar with Javadoc. 

I think it is highly possible. You would need 
to read in a series of files, select the 
relevant stuff, and write to a master file. 
In Stata, you _could_ read in do files 
as string variables, but a better approach 
would probably be based on -file-. 

However, it would be surprising if anyone had 
anticipated your needs by writing some Stata 
code to do precisely this. Also, fond though 
I am of Stata, if this were my problem I would 
use some scripting language (Awk, Perl, Python, 
etc., etc.) or programmable text 
editor to automate this task. 

Iben Fasterholdt
> Is it possible to automatically generate documentation for 
> Stata do-files in
> the same fashion as in for example javadoc?
> Introduction to javadoc, see the link below:
> We would like to be able to write something like the following:
> /*
> * @author (our names)
> * @version (versioninformation)
> * @description (description and usage of the program)
> * @param (program parameters)
> */
> program define ....
> syntax ......
> .
> .
> .
> end
> We would like to have a script that can gather all this 
> information from
> different do-files, to one documentation-file.  Does anyone 
> know of such a
> script / program?

This email and any files transmitted with it are confidential and
intended solely for the use of the individual or entity to whom they
are addressed. If you have received this email in error please notify
the system manager.

This footnote also confirms that this email message has been swept for the presence of computer viruses.


*   For searches and help try:

© Copyright 1996–2017 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index