1 /******************************************************************************

     2  *

     3  * Copyright (C) 1997-2008 by Dimitri van Heesch.

     4  *

     5  * Permission to use, copy, modify, and distribute this software and its

     6  * documentation under the terms of the GNU General Public License is hereby 

     7  * granted. No representations are made about the suitability of this software 

     8  * for any purpose. It is provided "as is" without express or implied warranty.

     9  * See the GNU General Public License for more details.

    10  *

    11  * Documents produced by Doxygen are derivative works derived from the

    12  * input used in their production; they are not affected by this license.

    13  *

    14  */

    15 

    16 #ifndef COMMENTSCAN_H

    17 #define COMMENTSCAN_H

    18 

    19 #include "qtbc.h"

    20 #include "entry.h"

    21 

    22 class ParserInterface;

    23 

    24 /** @file

    25  *  @brief Interface for the comment block parser */

    26 

    27 /** Invokes the comment block parser with the request to parse a 

    28  *  single comment block.

    29  *  @param[in] parser The language parse that invoked this function.

    30  *         The comment block parse may invoke 

    31  *         ParserInterface::parsePrototype() in order to parse

    32  *         the argument of a @@fn command.

    33  *  @param[in] curEntry The Entry to which the comment block belongs.

    34  *         Any information (like documentation) that is found in

    35  *         the comment block will be stored in this entry.

    36  *  @param[in] comment A string representing the actual comment block.

    37  *         Note that leading *'s are already stripped from the comment block.

    38  *  @param[in] fileName The name of the file in which the comment is found.

    39  *         Mainly used for producing warnings.

    40  *  @param[in,out] lineNr The line number at which the comment block was found.

    41  *         When the function returns it will be set to the last line parsed.

    42  *  @param[in] isBrief TRUE iff this comment block represents a brief description.

    43  *  @param[in] isJavaDocStyle TRUE iff this comment block is in "JavaDoc" style.

    44  *         This means that it starts as a brief description until the end of

    45  *         the sentences is found and then proceeds as a detailed description.

    46  *  @param[in] isInbody TRUE iff this comment block is located in the body of

    47  *         a function.

    48  *  @param[in,out] prot The protection level in which this comment block was

    49  *         found. Commands in the comment block may override this.

    50  *  @param[in,out] position The character position within \a comment where the

    51  *         comment block starts. Typically used in case the comment block

    52  *         contains multiple structural commands.

    53  *  @param[out] newEntryNeeded Boolean that is TRUE if the comment block parser

    54  *         finds that a the comment block finishes the entry and a new one

    55  *         needs to be started.

    56  *  @returns TRUE if the comment requires further processing. The

    57  *         parameter \a newEntryNeeded will typically be true in this case and

    58  *         \a position will indicate the offset inside the \a comment string

    59  *         where to proceed parsing. FALSE indicates no further processing is

    60  *         needed.

    61  */

    62 bool parseCommentBlock(ParserInterface *parser,

    63                        Entry *curEntry,

    64                        const QCString &comment,

    65 	               const QCString &fileName,

    66 		       int  &lineNr,

    67 		       bool isBrief,

    68 		       bool isJavaDocStyle,

    69                        bool isInbody,

    70 		       Protection &prot,

    71                        int &position,

    72                        bool &newEntryNeeded

    73 		     );

    74 

    75 void groupEnterFile(const char *file,int line);

    76 void groupLeaveFile(const char *file,int line);

    77 void groupLeaveCompound(const char *file,int line,const char *name);

    78 void groupEnterCompound(const char *file,int line,const char *name);

    79 void openGroup(Entry *e,const char *file,int line);

    80 void closeGroup(Entry *,const char *file,int line);

    81 void initGroupInfo(Entry *e);

    82 

    83 

    84 #endif