diff options
Diffstat (limited to 'docs/users_guide_2_src/06_comments.txt')
-rwxr-xr-x | docs/users_guide_2_src/06_comments.txt | 99 |
1 files changed, 99 insertions, 0 deletions
diff --git a/docs/users_guide_2_src/06_comments.txt b/docs/users_guide_2_src/06_comments.txt new file mode 100755 index 0000000..36323cf --- /dev/null +++ b/docs/users_guide_2_src/06_comments.txt @@ -0,0 +1,99 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Comments} +\label{comments} + +Comments are used to mark notes, explanations, and decorative text that should +not appear in the output. Cheetah maintains the comments in the Python module +it generates from the Cheetah source code. There are two forms of the comment +directive: single-line and multi-line. + +All text in a template definition that lies between two hash characters +(\code{\#\#}) and the end of the line is treated as a single-line comment and +will not show up in the output, unless the two hash characters are escaped with +a backslash. +\begin{verbatim} +##============================= this is a decorative comment-bar +$var ## this is an end-of-line comment +##============================= +\end{verbatim} + +Any text between \code{\#*} and \code{*\#} will be treated as a multi-line +comment. +\begin{verbatim} +#* + Here is some multiline + comment text +*# +\end{verbatim} + +If you put blank lines around method definitions or loops to separate them, +be aware that the blank lines will be output as is. To avoid this, make sure +the blank lines are enclosed in a comment. Since you normally have a +comment before the next method definition (right?), you can just extend that +comment to include the blank lines after the previous method definition, like +so: +\begin{verbatim} +#def method1 +... lines ... +#end def +#* + + + Description of method2. + $arg1, string, a phrase. +*# +#def method2($arg1) +... lines ... +#end def +\end{verbatim} + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Docstring Comments} +\label{comments.docstring} + +Python modules, classes, and methods can be documented with inline +'documentation strings' (aka 'docstrings'). Docstrings, unlike comments, are +accesible at run-time. Thus, they provide a useful hook for interactive help +utilities. + +Cheetah comments can be transformed into doctrings by adding one of the +following prefixes: + +\begin{verbatim} +##doc: This text will be added to the method docstring +#*doc: If your template file is MyTemplate.tmpl, running "cheetah compile" + on it will produce MyTemplate.py, with a class MyTemplate in it, + containing a method .respond(). This text will be in the .respond() + method's docstring. *# + +##doc-method: This text will also be added to .respond()'s docstring +#*doc-method: This text will also be added to .respond()'s docstring *# + +##doc-class: This text will be added to the MyTemplate class docstring +#*doc-class: This text will be added to the MyTemplate class docstring *# + +##doc-module: This text will be added to the module docstring MyTemplate.py +#*doc-module: This text will be added to the module docstring MyTemplate.py*# +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Header Comments} +\label{comments.headers} +Cheetah comments can also be transformed into module header comments using the +following syntax: + +\begin{verbatim} +##header: This text will be added to the module header comment +#*header: This text will be added to the module header comment *# +\end{verbatim} + +Note the difference between \code{\#\#doc-module: } and \code{header: }: +``cheetah-compile'' puts \code{\#\#doc-module: } text inside the module +docstring. \code{header: } makes the text go {\em above} the docstring, as a +set of \#-prefixed comment lines. + +% Local Variables: +% TeX-master: "users_guide" +% End: |