@FWEB{} allows a variety of commenting styles. The visible comments are in
the font \cmntfont
, which defaults to \mainfont
, a
ten-point Roman font.
@z...@x
$KEYWORD
: Value of global RCS-like keyword, section `@K': Extract global RCS-like keyword (source files), or section `@k': Access local RCS-like keyword (include
files)].
@%
@%%
For example,
@z Author: J. A. Krommes @x @c @% This sets the global language to C. @* EXAMPLE.
`/* ... */' is a long comment (it may extend over several lines).
`// ...' is a short comment (terminated by the next newline).
`@(...@)' is a meta-comment. Meta-comments are a localized form of the N mode (see section LANGUAGES). Tangled meta-comments are begun by the contents of the style-file entry `meta.top' and terminated by `meta.bottom'. Each line of the meta-comment is begun by `meta.prefix'. Woven meta-comments are begun by `meta_code.begin' and ended by `meta_code.end'. See section Miscellaneous style-file parameters.
@n @a program main /* Get input. */ call get_input // Read the parameter file. /* Process information. Comments like this can be split over several lines. */ @( Meta-comments provide a poor-person's alignment feature i --- counter x --- data value @) i = 1 x = 2.0 call exec(i,x) end
The use of meta-comments is not recommended; they are only
marginally supported. Use ordinary long comments
instead. Inside of them, use the various powerful features of TeX or
LaTeX (such as \halign
or
\begin{verbatim}
...
\end{verbatim}
) to format
your comment appropriately.
During development, one frequently desires to temporarily comment out a
section of code. C programmers sometimes try to do this by enclosing the
code in /*...*/
, but this is not good
style for several reasons. First, it is impossible if the code itself
includes comments, since comments do not nest in C. Second, @FWEAVE{}
will treat the commented code as TeX rather than C code and will (at best)
format it very poorly. In fact, LaTeX will frequently complain,
because the commented code might contain characters such as underscores
that TeX expects to be in math mode. (Those are dealt with
automatically when @FWEAVE{} is in code mode.) The trivial example
`/* a_b; */' is sufficient to illustrate this point.
The proper way of commenting out sections of code is to use preprocessor
constructions: #if 0...#endif
in C, or more generally @#if
0...@#endif
(usable in all languages). (The @FWEB{} preprocessor is
described in section Preprocessing.) With this method, there is no
trouble with nested comments, and @FWEAVE{} will continue to format
the code as code, so the documentation will make sense.
For FORTRAN programmers converting an existing code to @FWEB{}, the `-nC' option (see section `-nC': Ignore single-line comments [FORTRAN]) may be helpful.
Go to the first, previous, next, last section, table of contents.