% This LaTeX file generated by cxref
% cxref program (c) Andrew M. Bishop 1995,96,97.

\markboth{File comment.c}{File comment.c}
\section{File comment.c}
\label{file_comment.c}

{\bf RCS Header: /home/amb/cxref/RCS/comment.c 1.20 1998/12/22 14:26:26 amb Exp }

\smallskip

  C Cross Referencing \& Documentation tool. Version 1.5.

  Collects the comments from the parser.


\subsection*{Included Files}

\begin{cxreftabi}
{\stt \#include <stdlib.h>} &\\
\end{cxreftabi}

\medskip
\begin{cxreftabi}
{\stt \#include <stdio.h>} &\\
\end{cxreftabi}

\medskip
\begin{cxreftabi}
{\stt \#include <string.h>} &\\
\end{cxreftabi}

\medskip
\begin{cxreftabi}
{\stt \#include "memory.h"} &\cxreffile{memory.h}\\
\end{cxreftabi}

\medskip
\begin{cxreftabi}
{\stt \#include "datatype.h"} &\cxreffile{datatype.h}\\
\end{cxreftabi}

\medskip
\begin{cxreftabi}
{\stt \#include "cxref.h"} &\cxreffile{cxref.h}\\
\hspace*{0.2in}{\stt \#include "datatype.h"} &\cxreffile{datatype.h}\\
\end{cxreftabi}


\subsection*{Preprocessor definitions}

 Turn on the debugging in this file. 

\smallskip
{\stt \#define DEBUG 0}


\subsection{Variables}


\subsubsection{External Variables}

{\bf option\_verbatim\_comments}
\label{var_option_verbatim_comments_comment.c}

 The option to insert the comments verbatim into the output. 

\smallskip
{\stt extern int option\_verbatim\_comments}

\smallskip
\begin{cxreftabiii}
Defined in:& cxref.c & \ & \cxrefvar{option_verbatim_comments}{cxref.c}\\
\end{cxreftabiii}

\medskip
{\bf CurFile}
\label{var_CurFile_comment.c}

 The file that is currently being processed. 

\smallskip
{\stt extern File CurFile}

\smallskip
\begin{cxreftabiii}
Defined in:& cxref.c & \ & \cxrefvar{CurFile}{cxref.c}\\
\end{cxreftabiii}

\medskip
{\bf parse\_file}
\label{var_parse_file_comment.c}

 The name of the current file. 

\smallskip
{\stt extern char* parse\_file}

\smallskip
\begin{cxreftabiii}
Defined in:& parse-lex.c & \ & \cxrefvar{parse_file}{parse-lex.c}\\
\end{cxreftabiii}


\subsubsection{Local Variables}

{\bf current\_comment}
\label{var_current_comment_comment.c}

 The current (latest) comment. 

\smallskip
{\stt static char* current\_comment}

\smallskip
\begin{cxreftabiii}
Used in:\ & DeleteComment() & \ & \cxreffunc{DeleteComment}{comment.c}\\
\ & GetCurrentComment() & \ & \cxreffunc{GetCurrentComment}{comment.c}\\
\ & SeenComment() & \ & \cxreffunc{SeenComment}{comment.c}\\
\ & SetCurrentComment() & \ & \cxreffunc{SetCurrentComment}{comment.c}\\
\end{cxreftabiii}

\medskip
{\bf malloc\_comment}
\label{var_malloc_comment_comment.c}

 The malloced string for the current comment. 

\smallskip
{\stt static char* malloc\_comment}

\smallskip
\begin{cxreftabiii}
Used in:\ & DeleteComment() & \ & \cxreffunc{DeleteComment}{comment.c}\\
\ & SeenComment() & \ & \cxreffunc{SeenComment}{comment.c}\\
\ & SetCurrentComment() & \ & \cxreffunc{SetCurrentComment}{comment.c}\\
\end{cxreftabiii}

\medskip
{\bf comment\_ended}
\label{var_comment_ended_comment.c}

 The status of the current comment. 

\smallskip
{\stt static int comment\_ended}

\smallskip
\begin{cxreftabiii}
Used in:\ & DeleteComment() & \ & \cxreffunc{DeleteComment}{comment.c}\\
\ & SeenComment() & \ & \cxreffunc{SeenComment}{comment.c}\\
\end{cxreftabiii}


\subsection{Functions}


\subsubsection{Global Function DeleteComment()}
\label{func_DeleteComment_comment.c}

  Delete the malloced string for the comment

\smallskip
{\stt void DeleteComment ( void )}

\smallskip
\begin{cxreftabiii}
Prototype:& cxref.h & \ & \cxreffile{cxref.h}\\
Calls:\ & SafeFree() & memory.c & \cxreffunc{SafeFree}{memory.c}\\
Called by:\ & main() & cxref.c & \cxreffunc{main}{cxref.c}\\
Refs Var:\ & comment\_ended & comment.c & \cxrefvar{comment_ended}{comment.c}\\
\cxreftabbreak{cxreftabiii}
\ & current\_comment & comment.c & \cxrefvar{current_comment}{comment.c}\\
\ & malloc\_comment & comment.c & \cxrefvar{malloc_comment}{comment.c}\\
\end{cxreftabiii}


\subsubsection{Global Function GetCurrentComment()}
\label{func_GetCurrentComment_comment.c}

  Provide the current (latest) comment.

\smallskip
{\stt char* GetCurrentComment ( void )}

\smallskip
\begin{cxrefarglist}
\cxrefargitem{char* GetCurrentComment} Returns the current (latest) comment.
\end{cxrefarglist}

\smallskip
\begin{cxreftabiii}
Prototype:& cxref.h & \ & \cxreffile{cxref.h}\\
Called by:\ & SeenDefine() & preproc.c & \cxreffunc{SeenDefine}{preproc.c}\\
\ & SeenDefineComment() & preproc.c & \cxreffunc{SeenDefineComment}{preproc.c}\\
\ & SeenDefineFuncArgComment() & preproc.c & \cxreffunc{SeenDefineFuncArgComment}{preproc.c}\\
\cxreftabbreak{cxreftabiii}
\ & SeenFunctionArg() & func.c & \cxreffunc{SeenFunctionArg}{func.c}\\
\ & SeenFunctionDeclaration() & func.c & \cxreffunc{SeenFunctionDeclaration}{func.c}\\
\ & SeenFunctionDefinition() & func.c & \cxreffunc{SeenFunctionDefinition}{func.c}\\
\ & SeenInclude() & preproc.c & \cxreffunc{SeenInclude}{preproc.c}\\
\ & SeenIncludeComment() & preproc.c & \cxreffunc{SeenIncludeComment}{preproc.c}\\
\ & SeenStructUnionComp() & type.c & \cxreffunc{SeenStructUnionComp}{type.c}\\
\ & SeenStructUnionStart() & type.c & \cxreffunc{SeenStructUnionStart}{type.c}\\
\ & SeenTypedef() & type.c & \cxreffunc{SeenTypedef}{type.c}\\
\cxreftabbreak{cxreftabiii}
\ & SeenVariableDefinition() & var.c & \cxreffunc{SeenVariableDefinition}{var.c}\\
\ & yylex() & parse-lex.c & \cxreffunc{yylex}{parse-lex.c}\\
\ & yyparse() & parse-yacc.c & \cxreffunc{yyparse}{parse-yacc.c}\\
Refs Var:\ & current\_comment & comment.c & \cxrefvar{current_comment}{comment.c}\\
\end{cxreftabiii}


\subsubsection{Global Function SeenComment()}
\label{func_SeenComment_comment.c}

  Function that is called when a comment or part of one is seen. The comment is built up until an end of comment is signaled.

\smallskip
{\stt void SeenComment ( char* c )}

\smallskip
\begin{cxrefarglist}
\cxrefargitem{char* c} The comment text. If c==0 then it is a file (/ * * comment * * /) comment
                            if c==1 then it is the other special comment (/ * + comment + * /).
                            if c==2 then it is a normal comment (/ * comment * /).
                            if c==3 then it is not a comment.
\end{cxrefarglist}

\smallskip
\begin{cxreftabiii}
Prototype:& cxref.h & \ & \cxreffile{cxref.h}\\
Calls:\ & SafeMalloc() & memory.c & \cxreffunc{SafeMalloc}{memory.c}\\
\ & SafeRealloc() & memory.c & \cxreffunc{SafeRealloc}{memory.c}\\
\ & SeenFileComment() & file.c & \cxreffunc{SeenFileComment}{file.c}\\
\cxreftabbreak{cxreftabiii}
\ & SeenFuncIntComment() & func.c & \cxreffunc{SeenFuncIntComment}{func.c}\\
\ & TidyCommentString() & comment.c & \cxreffunc{TidyCommentString}{comment.c}\\
\ & \cxreftabiiispan{ strcat(), strcmp(), strcpy(), strlen()} &\\
Called by:\ & yylex() & parse-lex.c & \cxreffunc{yylex}{parse-lex.c}\\
Refs Var:\ & CurFile & cxref.c & \cxrefvar{CurFile}{cxref.c}\\
\ & comment\_ended & comment.c & \cxrefvar{comment_ended}{comment.c}\\
\ & current\_comment & comment.c & \cxrefvar{current_comment}{comment.c}\\
\ & malloc\_comment & comment.c & \cxrefvar{malloc_comment}{comment.c}\\
\ & option\_verbatim\_comments & cxref.c & \cxrefvar{option_verbatim_comments}{cxref.c}\\
\cxreftabbreak{cxreftabiii}
\ & parse\_file & parse-lex.c & \cxrefvar{parse_file}{parse-lex.c}\\
\end{cxreftabiii}


\subsubsection{Global Function SetCurrentComment()}
\label{func_SetCurrentComment_comment.c}

  Set the current (latest) comment.

\smallskip
{\stt void SetCurrentComment ( char* comment )}

\smallskip
\begin{cxrefarglist}
\cxrefargitem{char* comment} The comment.
\end{cxrefarglist}

\smallskip
\begin{cxreftabiii}
Prototype:& cxref.h & \ & \cxreffile{cxref.h}\\
Calls:\ & SafeRealloc() & memory.c & \cxreffunc{SafeRealloc}{memory.c}\\
\ & \cxreftabiiispan{ strcpy(), strlen()} &\\
Called by:\ & SeenFileChange() & preproc.c & \cxreffunc{SeenFileChange}{preproc.c}\\
\ & yyparse() & parse-yacc.c & \cxreffunc{yyparse}{parse-yacc.c}\\
\cxreftabbreak{cxreftabiii}
Refs Var:\ & current\_comment & comment.c & \cxrefvar{current_comment}{comment.c}\\
\ & malloc\_comment & comment.c & \cxrefvar{malloc_comment}{comment.c}\\
\end{cxreftabiii}


\subsubsection{Global Function SplitComment()}
\label{func_SplitComment_comment.c}

  A function to split out the arguments etc from a comment,
  for example the function argument comments are separated using this.

\smallskip
{\stt char* SplitComment ( char** original, char* name )}

\smallskip
\begin{cxrefarglist}
\cxrefargitem{char* SplitComment} Returns the required comment.
\cxrefargitem{char** original} A pointer to the original comment, this is altered in the process.
\cxrefargitem{char* name} The name that is to be cut out from the comment.
\end{cxrefarglist}

\smallskip
  A most clever function that ignores spaces so that 'char* b' and 'char *b' match.

\smallskip
\begin{cxreftabiii}
Prototype:& cxref.h & \ & \cxreffile{cxref.h}\\
Calls:\ & ConcatStrings() & memory.c & \cxreffunc{ConcatStrings}{memory.c}\\
\ & CopyString() & memory.c & \cxreffunc{CopyString}{memory.c}\\
\ & SafeFree() & memory.c & \cxreffunc{SafeFree}{memory.c}\\
\cxreftabbreak{cxreftabiii}
\ & SafeMallocString() & memory.c & \cxreffunc{SafeMallocString}{memory.c}\\
\ & TidyCommentString() & comment.c & \cxreffunc{TidyCommentString}{comment.c}\\
\ & \cxreftabiiispan{ strlen(), strstr()} &\\
Called by:\ & SeenDefineFunctionArg() & preproc.c & \cxreffunc{SeenDefineFunctionArg}{preproc.c}\\
\ & SeenFunctionArg() & func.c & \cxreffunc{SeenFunctionArg}{func.c}\\
\ & SeenFunctionDefinition() & func.c & \cxreffunc{SeenFunctionDefinition}{func.c}\\
\end{cxreftabiii}


\subsubsection{Local Function TidyCommentString()}
\label{func_TidyCommentString_comment.c}

  Tidy up the current comment string by snipping off trailing and leading junk.

\smallskip
{\stt static void TidyCommentString ( char** string, int spaces )}

\smallskip
\begin{cxrefarglist}
\cxrefargitem{char** string} The string that is to be tidied.
\cxrefargitem{int spaces} Indicates that leading and trailing whitespace are to be removed as well.
\end{cxrefarglist}

\smallskip
\begin{cxreftabiii}
Prototype:& comment.c & \ & \cxreffile{comment.c}\\
Calls:\ & \cxreftabiiispan{ strlen()} &\\
Called by:\ & SeenComment() & comment.c & \cxreffunc{SeenComment}{comment.c}\\
\ & SplitComment() & comment.c & \cxreffunc{SplitComment}{comment.c}\\
\end{cxreftabiii}

