src/definition.h

   1 /******************************************************************************
   2  *
   3  *
   4  *
   5  * Copyright (C) 1997-2014 by Dimitri van Heesch.
   6  *
   7  * Permission to use, copy, modify, and distribute this software and its
   8  * documentation under the terms of the GNU General Public License is hereby
   9  * granted. No representations are made about the suitability of this software
  10  * for any purpose. It is provided "as is" without express or implied warranty.
  11  * See the GNU General Public License for more details.
  12  *
  13  * Documents produced by Doxygen are derivative works derived from the
  14  * input used in their production; they are not affected by this license.
  15  *
  16  */
  17
  18 #ifndef DEFINITION_H
  19 #define DEFINITION_H
  20
  21 #include <qlist.h>
  22 #include <qdict.h>
  23
  24 #include "types.h"
  25
  26 class FileDef;
  27 class OutputList;
  28 class SectionDict;
  29 class MemberSDict;
  30 class MemberDef;
  31 class GroupDef;
  32 class GroupList;
  33 struct ListItemInfo;
  34 struct SectionInfo;
  35 class Definition;
  36 class DefinitionImpl;
  37
  38 /** Data associated with a detailed description. */
  39 struct DocInfo
  40 {
  41     QCString doc;
  42     int      line;
  43     QCString file;
  44 };
  45
  46 /** Data associated with a brief description. */
  47 struct BriefInfo
  48 {
  49     QCString doc;
  50     QCString tooltip;
  51     int      line;
  52     QCString file;
  53 };
  54
  55 /** Data associated with description found in the body. */
  56 struct BodyInfo
  57 {
  58     int      startLine;   //!< line number of the start of the definition
  59     int      endLine;     //!< line number of the end of the definition
  60     FileDef *fileDef;     //!< file definition containing the function body
  61 };
  62
  63 /** Abstract interface for a Definition or DefinitionList */
  64 class DefinitionIntf
  65 {
  66   public:
  67     DefinitionIntf() {}
  68     virtual ~DefinitionIntf() {}
  69     /*! Types of derived classes */
  70     enum DefType
  71     {
  72       TypeClass      = 0,
  73       TypeFile       = 1,
  74       TypeNamespace  = 2,
  75       TypeMember     = 3,
  76       TypeGroup      = 4,
  77       TypePackage    = 5,
  78       TypePage       = 6,
  79       TypeDir        = 7,
  80       TypeSymbolList = 8
  81     };
  82     /*! Use this for dynamic inspection of the type of the derived class */
  83     virtual DefType definitionType() const = 0;
  84 };
  85
  86 /** The common base class of all entity definitions found in the sources.
  87  *
  88  *  This can be a class or a member function, or a file, or a namespace, etc.
  89  *  Use definitionType() to find which type of definition this is.
  90  */
  91 class Definition : public DefinitionIntf
  92 {
  93   public:
  94
  95     /*! Create a new definition */
  96     Definition(
  97         const char *defFileName,int defLine,int defColumn,
  98         const char *name,const char *b=0,const char *d=0,
  99         bool isSymbol=TRUE);
 100
 101     /*! Destroys the definition */
 102     virtual ~Definition();
 103
 104     //-----------------------------------------------------------------------------------
 105     // ----  getters -----
 106     //-----------------------------------------------------------------------------------
 107
 108     /*! Returns the name of the definition */
 109     const QCString& name() const { return m_name; }
 110
 111     /*! Returns the name of the definition as it appears in the output */
 112     virtual QCString displayName(bool includeScope=TRUE) const = 0;
 113
 114     /*! Returns the local name without any scope qualifiers. */
 115     QCString localName() const;
 116
 117     /*! Returns the fully qualified name of this definition
 118      */
 119     virtual QCString qualifiedName() const;
 120
 121     /*! Returns the name of this definition as it appears in the symbol map.
 122      */
 123     QCString symbolName() const;
 124
 125     /*! Returns the base file name (without extension) of this definition.
 126      *  as it is referenced to/written to disk.
 127      */
 128     virtual QCString getOutputFileBase() const = 0;
 129
 130     /*! Returns the anchor within a page where this item can be found */
 131     virtual QCString anchor() const = 0;
 132
 133     /*! Returns the name of the source listing of this definition. */
 134     virtual QCString getSourceFileBase() const;
 135
 136     /*! Returns the anchor of the source listing of this definition. */
 137     virtual QCString getSourceAnchor() const;
 138
 139     /*! Returns the detailed description of this definition */
 140     virtual QCString documentation() const;
 141
 142     /*! Returns the line number at which the detailed documentation was found. */
 143     int docLine() const;
 144
 145     /*! Returns the file in which the detailed documentation block was found.
 146      *  This can differ from getDefFileName().
 147      */
 148     QCString docFile() const;
 149
 150     /*! Returns the brief description of this definition. This can include commands. */
 151     virtual QCString briefDescription(bool abbreviate=FALSE) const;
 152
 153     /*! Returns a plain text version of the brief description suitable for use
 154      *  as a tool tip.
 155      */
 156     QCString briefDescriptionAsTooltip() const;
 157
 158     /*! Returns the line number at which the brief description was found. */
 159     int briefLine() const;
 160
 161     /*! Returns the documentation found inside the body of a member */
 162     QCString inbodyDocumentation() const;
 163
 164     /*! Returns the file in which the in body documentation was found */
 165     QCString inbodyFile() const;
 166
 167     /*! Returns the line at which the first in body documentation
 168         part was found */
 169     int inbodyLine() const;
 170
 171     /*! Returns the file in which the brief description was found.
 172      *  This can differ from getDefFileName().
 173      */
 174     QCString briefFile() const;
 175
 176     /*! returns the file in which this definition was found */
 177     QCString getDefFileName() const;
 178
 179     /*! returns the extension of the file in which this definition was found */
 180     QCString getDefFileExtension() const;
 181
 182     /*! returns the line number at which the definition was found */
 183     int getDefLine() const { return m_defLine; }
 184
 185     /*! returns the column number at which the definition was found */
 186     int getDefColumn() const { return m_defColumn; }
 187
 188     /*! Returns TRUE iff the definition is documented
 189      *  (which could be generated documentation)
 190      *  @see hasUserDocumentation()
 191      */
 192     virtual bool hasDocumentation() const;
 193
 194     /*! Returns TRUE iff the definition is documented by the user. */
 195     virtual bool hasUserDocumentation() const;
 196
 197     /*! Returns TRUE iff it is possible to link to this item within this
 198      *  project.
 199      */
 200     virtual bool isLinkableInProject() const = 0;
 201
 202     /*! Returns TRUE iff it is possible to link to this item. This can
 203      *  be a link to another project imported via a tag file.
 204      */
 205     virtual bool isLinkable() const = 0;
 206
 207     /*! Returns TRUE iff the name is part of this project and
 208      *  may appear in the output
 209      */
 210     virtual bool isVisibleInProject() const;
 211
 212     /*! Returns TRUE iff the name may appear in the output */
 213     virtual bool isVisible() const;
 214
 215     /*! Returns TRUE iff this item is supposed to be hidden from the output. */
 216     bool isHidden() const;
 217
 218     /*! returns TRUE if this entity was artificially introduced, for
 219      *  instance because it is used to show a template instantiation relation.
 220      */
 221     bool isArtificial() const;
 222
 223     /*! If this definition was imported via a tag file, this function
 224      *  returns the tagfile for the external project. This can be
 225      *  translated into an external link target via
 226      *  Doxygen::tagDestinationDict
 227      */
 228     virtual QCString getReference() const;
 229
 230     /*! Returns TRUE if this definition is imported via a tag file. */
 231     virtual bool isReference() const;
 232
 233     /*! Returns the first line of the body of this item (applicable to classes and
 234      *  functions).
 235      */
 236     int getStartBodyLine() const;
 237
 238     /*! Returns the last line of the body of this item (applicable to classes and
 239      *  functions).
 240      */
 241     int getEndBodyLine() const;
 242
 243     /*! Returns the file in which the body of this item is located or 0 if no
 244      *  body is available.
 245      */
 246     FileDef *getBodyDef() const;
 247
 248     /** Returns the programming language this definition was written in. */
 249     SrcLangExt getLanguage() const;
 250
 251     GroupList *partOfGroups() const;
 252
 253     QList<ListItemInfo> *xrefListItems() const;
 254
 255     virtual Definition *findInnerCompound(const char *name);
 256     virtual Definition *getOuterScope() const;
 257
 258     MemberSDict *getReferencesMembers() const;
 259     MemberSDict *getReferencedByMembers() const;
 260
 261     bool hasSections() const;
 262     bool hasSources() const;
 263
 264     /** returns TRUE if this class has a brief description */
 265     bool hasBriefDescription() const;
 266
 267     QCString id() const;
 268
 269     //-----------------------------------------------------------------------------------
 270     // ----  setters -----
 271     //-----------------------------------------------------------------------------------
 272
 273     /*! Sets a new \a name for the definition */
 274     void setName(const char *name);
 275
 276     /*! Sets a unique id for the symbol. Used for libclang integration. */
 277     void setId(const char *name);
 278
 279     /*! Sets the documentation of this definition to \a d. */
 280     virtual void setDocumentation(const char *d,const char *docFile,int docLine,bool stripWhiteSpace=TRUE);
 281
 282     /*! Sets the brief description of this definition to \a b.
 283      *  A dot is added to the sentence if not available.
 284      */
 285     virtual void setBriefDescription(const char *b,const char *briefFile,int briefLine);
 286
 287     /*! Set the documentation that was found inside the body of an item.
 288      *  If there was already some documentation set, the new documentation
 289      *  will be appended.
 290      */
 291     virtual void setInbodyDocumentation(const char *d,const char *docFile,int docLine);
 292
 293     /*! Sets the tag file id via which this definition was imported. */
 294     void setReference(const char *r);
 295
 296     /*! Add the list of anchors that mark the sections that are found in the
 297      * documentation.
 298      */
 299     void addSectionsToDefinition(QList<SectionInfo> *anchorList);
 300
 301     // source references
 302     void setBodySegment(int bls,int ble);
 303     void setBodyDef(FileDef *fd);
 304     void addSourceReferencedBy(MemberDef *d);
 305     void addSourceReferences(MemberDef *d);
 306
 307     void setRefItems(const QList<ListItemInfo> *sli);
 308     void mergeRefItems(Definition *d);
 309     virtual void addInnerCompound(Definition *d);
 310     virtual void setOuterScope(Definition *d);
 311
 312     virtual void setHidden(bool b);
 313
 314     void setArtificial(bool b);
 315     void setLanguage(SrcLangExt lang);
 316
 317     //-----------------------------------------------------------------------------------
 318     // --- actions ----
 319     //-----------------------------------------------------------------------------------
 320
 321     QCString convertNameToFile(const char *name,bool allowDots=FALSE) const;
 322     void writeSourceDef(OutputList &ol,const char *scopeName);
 323     void writeInlineCode(OutputList &ol,const char *scopeName);
 324     void writeSourceRefs(OutputList &ol,const char *scopeName);
 325     void writeSourceReffedBy(OutputList &ol,const char *scopeName);
 326     void makePartOfGroup(GroupDef *gd);
 327     //void writePathFragment(OutputList &ol) const;
 328     void writeNavigationPath(OutputList &ol) const;
 329     QCString navigationPathAsString() const;
 330     virtual void writeQuickMemberLinks(OutputList &,MemberDef *) const {}
 331     virtual void writeSummaryLinks(OutputList &) {}
 332     QCString pathFragment() const;
 333
 334     /*! Writes the documentation anchors of the definition to
 335      *  the Doxygen::tagFile stream.
 336      */
 337     void writeDocAnchorsToTagFile();
 338     void setLocalName(const QCString name);
 339
 340     void addSectionsToIndex();
 341     void writeToc(OutputList &ol);
 342
 343   protected:
 344
 345     Definition(const Definition &d);
 346
 347   private:
 348     static void addToMap(const char *name,Definition *d);
 349     static void removeFromMap(Definition *d);
 350
 351     void _setSymbolName(const QCString &name);
 352
 353     int  _getXRefListId(const char *listName) const;
 354     void _writeSourceRefList(OutputList &ol,const char *scopeName,
 355                        const QCString &text,MemberSDict *members,bool);
 356     void _setBriefDescription(const char *b,const char *briefFile,int briefLine);
 357     void _setDocumentation(const char *d,const char *docFile,int docLine,bool stripWhiteSpace,bool atTop);
 358     void _setInbodyDocumentation(const char *d,const char *docFile,int docLine);
 359     bool _docsAlreadyAdded(const QCString &doc,QCString &sigList);
 360     DefinitionImpl *m_impl; // internal structure holding all private data
 361     QCString m_name;
 362     bool m_isSymbol;
 363     QCString m_symbolName;
 364     int m_defLine;
 365     int m_defColumn;
 366 };
 367
 368 /** A list of Definition objects. */
 369 class DefinitionList : public QList<Definition>, public DefinitionIntf
 370 {
 371   public:
 372     ~DefinitionList() {}
 373     DefType definitionType() const { return TypeSymbolList; }
 374     int compareValues(const Definition *item1,const Definition *item2) const
 375     {
 376       return qstricmp(item1->name(),item2->name());
 377     }
 378
 379 };
 380
 381 /** An iterator for Definition objects in a DefinitionList. */
 382 class DefinitionListIterator : public QListIterator<Definition>
 383 {
 384   public:
 385     DefinitionListIterator(const DefinitionList &l) :
 386       QListIterator<Definition>(l) {}
 387     ~DefinitionListIterator() {}
 388 };
 389
 390 /** Reads a fragment from file \a fileName starting with line \a startLine
 391  *  and ending with line \a endLine. The result is returned as a string
 392  *  via \a result. The function returns TRUE if successful and FALSE
 393  *  in case of an error.
 394  */
 395 bool readCodeFragment(const char *fileName,
 396                       int &startLine,int &endLine,
 397                       QCString &result);
 398 #endif