tcldoc Description 


This script generates automatically HTML Files giving the list of
the function in a TCL file with all the interesting things about
them.
After reading Java documentation, I adapted it to my own needs.
So here is a completed example:
proc dummy {param1 {param2 "default value"} } {
#
# Function existing just for as
# an example purpose
#
# @param param1 : First parameter with a long
# comment on several distinct
# line
# @param param2 : Comment for the 2nd parameter
# @global gl : Global variable to be returned
# @return This function return gl*gc
global gl gc

return gl*gc
}

Author : Jean-Michel AUGUSTO jma@acri.fr
Version : 0.6
See Also : Usage of the tcldoc

List of Functions

*doOutput
*getComment
*getsLine
*outputFctDefault
*outputFctTable
*outputHTML
*parseFile
*parseOptions
*printUsage
*resetFile
*resetOptions
*writeIndex
*writeSummaryDefault
*writeSummaryTable

Function doOutput
Function called to put on stdout a message if the verbose mode is on.

Parameters
msg Message to display

Global Parameters
options General Options of tcldoc

Function getComment
Function called to get the comments for a given procedure

Parameters
name Name of the Procedure/Function.

Global Parameters
infoProcComment The comment associated to the function
infoProcGlobal An array containing the comments associated to the globals used in the function
infoProcParam An array containing the comments associated to the parameters of the function.
infoProcReturn A String containing the comment associated to the return value of the function
listGlobal An array containing a per-function list of used global
options General Options of tcldoc

Function getsLine
Function called to get the next line in file identifier. It calls the 'gets' TCL function but it also counts several things like the total number of read lines and the number of comment lines.

Parameters
fileID File Identifier
line Name of the variable where to put the read line

Global Parameters
stats Array containing Statistics about the current process

Function outputFctDefault
Function called to make an HTML dump of the found structure. The parameters, comments and global parameters are delivered. The output is put on one file

Parameters
fileID File Identifier
file File Name

Global Parameters
commentFile Comments Associated to the whole file
commentFileNb Number of Lines for the file
infoProc array containing functions information
infoProcComment array containing all the sarting comments
infoProcDefault Array containing the Default values for the optional parameters
infoProcGlobal array containing all the global parameters
infoProcParam array containing parameters information
infoProcReturn array containing all the return comments.
listGlobal An array containing a per-function list of used global variables
listProc List of all recognised functions of the file
missingCommentFct List of non commented functions
missingCommentGlobal List of non commented globals
missingCommentParam List of non commented parameters
missingCommentReturn List of non commented return
options Array for prg options
stats Array containing Statistics about the current process

Function outputFctTable
Function called to make an HTML dump of the found structure. The parameters, comments and global parameters are delivered. The output is put on one file

Parameters
fileID File Identifier
file Filename corresponding to the actual structure

Global Parameters
commentFile Comments Associated to the whole file
commentFileNb Number of Lines for the file
infoProc array containing functions information
infoProcComment array containing all the sarting comments
infoProcDefault Array containing the Default values for the optional parameters
infoProcGlobal array containing all the global parameters
infoProcParam array containing parameters information
infoProcReturn array containing all the return comments.
listGlobal An array containing a per-function list of used global variables
listProc List of all recognised functions of the file
missingCommentFct List of non commented functions
missingCommentGlobal List of non commented globals
missingCommentParam List of non commented parameters
missingCommentReturn List of non commented return
options Array for prg options Array of the current options of the prog
stats Array containing Statistics about the current process

Function outputHTML
Function called to make an HTML dump of the found structure. The parameters, comments and global parameters are delivered. The output is put on one file

Parameters
file Filename corresponding to the actual structure

Global Parameters
commentFile Comments Associated to the whole file
commentFileNb Number of Comments
infoProc array containing functions information
infoProcComment array containing all the sarting comments
infoProcDefault Array containing the Default values for the optional parameters
infoProcErr Array containing the name of the erroneous functions.
infoProcGlobal array containing all the global parameters
infoProcParam array containing parameters information
infoProcReturn array containing all the return comments.
listGlobal An array containing a per-function list of used global variables
listProc List of all recognised functions of the file
options Array for prg options

Function parseFile
Function called to parse a Tcl/Tk file and then to creat the right structure for enabling the program to output description of the functions and parameters.

Parameters
file File to parse

Global Parameters
commentFile Comments Associated to the whole file.
commentFileNb Number of Comments associated to the whole file.
infoProc array containing functions information
infoProcComment array containing all the sarting comments
infoProcDefault Array containing the Default values for the optional parameters
infoProcErr Array containing the name of the erroneous functions.
infoProcGlobal array containing all the global parameters
infoProcParam array containing parameters information
infoProcReturn array containing all the return comments.
listProc List of all recognised functions of the file
options Array for prg options
stats Array containing Statistics about the current process

Function parseOptions
Function called to parse the arguments coming from the command line and to transfer them in options for the program.

Global Parameters
argv The Arguments passed to the Script
argv0 Name of the script
options Array of the current options of the prog

Function printUsage
Function called to print the usage of the script

Global Parameters
argv0 Name of the script
options Array of the current options of the prog

Function resetFile
Function called to reset all the information about a file.

Global Parameters
commentFile Comments Associated to the whole file
commentFileNb Number of Lines for the file
infoProc array containing functions information
infoProcComment array containing all the sarting comments
infoProcDefault Array containing the Default values for the optional parameters
infoProcGlobal array containing all the global parameters
infoProcParam array containing parameters information
listGlobal An array containing a per-function list of used global variables
listProc List of all recognised functions of the file

Function resetOptions
Function to reset the options of the program.

Global Parameters
options Array of the current options of the prog

Function writeIndex
Function called to set the header of an HTML file

Parameters
listFile List of file to handle

Global Parameters
generalFctList List of all the Functions.
missingCommentFct List of non commented functions
missingCommentGlobal List of non commented globals
missingCommentParam List of non commented parameters
missingCommentReturn List of non commented return
options Array of the current options of the prog
stats Array containing Statistics about the current process

Function writeSummaryDefault
Function called to generate a Summary in the default/normal format

Parameters
fileID file Identifier

Global Parameters
options Array for prg options
stats Array containing Statistics about the current process

Function writeSummaryTable
Function called to generate a Summary in a Table format

Parameters
fileID file Identifier

Global Parameters
options Array for prg options
stats Array containing Statistics about the current process

Back to Index File