src/definition.h

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