# File comment.c

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

C Cross Referencing & Documentation tool. Version 1.5.
Collects the comments from the parser.

## Included Files

- `#include <stdlib.h>`

- `#include <stdio.h>`

- `#include <string.h>`

- `#include "memory.h"`

- `#include "datatype.h"`

- `#include "cxref.h"`
  - `#include "datatype.h"`

## Preprocessor definitions

Turn on the debugging in this file.

`#define DEBUG 0`

## External Variables

option_verbatim_comments
The option to insert the comments verbatim into the output.

`extern int option_verbatim_comments`

Defined in: | cxref.c

CurFile
The file that is currently being processed.

`extern File CurFile`

Defined in: | cxref.c

parse_file
The name of the current file.

`extern char* parse_file`

Defined in: | parse-lex.c

## Local Variables

current_comment
The current (latest) comment.

`static char* current_comment`

Used in: | DeleteComment()
| GetCurrentComment()
| SeenComment()
| SetCurrentComment()

malloc_comment
The malloced string for the current comment.

`static char* malloc_comment`

Used in: | DeleteComment()
| SeenComment()
| SetCurrentComment()

comment_ended
The status of the current comment.

`static int comment_ended`

Used in: | DeleteComment()
| SeenComment()

## Global Function DeleteComment()

Delete the malloced string for the comment

`void DeleteComment ( void )`

Prototyped in: | cxref.h
Calls: | SafeFree() | memory.c
Called by: | main() | cxref.c
References Variables: | comment_ended | comment.c
| current_comment | comment.c
| malloc_comment | comment.c

## Global Function GetCurrentComment()

Provide the current (latest) comment.

`char* GetCurrentComment ( void )`

`char* GetCurrentComment`
  Returns the current (latest) comment.

Prototyped in: | cxref.h
Called by: | SeenDefine() | preproc.c
| SeenDefineComment() | preproc.c
| SeenDefineFuncArgComment() | preproc.c
| SeenFunctionArg() | func.c
| SeenFunctionDeclaration() | func.c
| SeenFunctionDefinition() | func.c
| SeenInclude() | preproc.c
| SeenIncludeComment() | preproc.c
| SeenStructUnionComp() | type.c
| SeenStructUnionStart() | type.c
| SeenTypedef() | type.c
| SeenVariableDefinition() | var.c
| yylex() | parse-lex.c
| yyparse() | parse-yacc.c
References Variables: | current_comment | comment.c

## Global Function SeenComment()

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.

`void SeenComment ( char* c )`

`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.

Prototyped in: | cxref.h
Calls: | SafeMalloc() | memory.c
| SafeRealloc() | memory.c
| SeenFileComment() | file.c
| SeenFuncIntComment() | func.c
| TidyCommentString() | comment.c
| strcat(), strcmp(), strcpy(), strlen()
Called by: | yylex() | parse-lex.c
References Variables: | CurFile | cxref.c
| comment_ended | comment.c
| current_comment | comment.c
| malloc_comment | comment.c
| option_verbatim_comments | cxref.c
| parse_file | parse-lex.c

## Global Function SetCurrentComment()

Set the current (latest) comment.

`void SetCurrentComment ( char* comment )`

`char* comment`
  The comment.

Prototyped in: | cxref.h
Calls: | SafeRealloc() | memory.c
| strcpy(), strlen()
Called by: | SeenFileChange() | preproc.c
| yyparse() | parse-yacc.c
References Variables: | current_comment | comment.c
| malloc_comment | comment.c

## Global Function SplitComment()

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

`char* SplitComment ( char** original, char* name )`

`char* SplitComment`
  Returns the required comment.
`char** original`
  A pointer to the original comment, this is altered in the process.
`char* name`
  The name that is to be cut out from the comment.

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

Prototyped in: | cxref.h
Calls: | ConcatStrings() | memory.c
| CopyString() | memory.c
| SafeFree() | memory.c
| SafeMallocString() | memory.c
| TidyCommentString() | comment.c
| strlen(), strstr()
Called by: | SeenDefineFunctionArg() | preproc.c
| SeenFunctionArg() | func.c
| SeenFunctionDefinition() | func.c

## Local Function TidyCommentString()

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

`static void TidyCommentString ( char** string, int spaces )`

`char** string`
  The string that is to be tidied.
`int spaces`
  Indicates that leading and trailing whitespace are to be removed as well.

Prototyped in: | comment.c
Calls: | strlen()
Called by: | SeenComment() | comment.c
| SplitComment() | comment.c