src/definition.h

   1 /******************************************************************************
   2  *
   3  * $Id: definition.h,v 1.21 2001/03/19 19:27:40 root Exp $
   4  *
   5  * Copyright (C) 1997-2012 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 "qtbc.h"
  22 #include <qlist.h>
  23 #include <qdict.h>
  24 #include <sys/types.h>
  25
  26 #include "lockingptr.h"
  27 #include "util.h"
  28
  29 class FileDef;
  30 class OutputList;
  31 class SectionDict;
  32 class MemberSDict;
  33 class MemberDef;
  34 class GroupDef;
  35 class GroupList;
  36 struct ListItemInfo;
  37 struct SectionInfo;
  38 class Definition;
  39 class DefinitionImpl;
  40
  41 /** Data associated with a detailed description. */
  42 struct DocInfo
  43 {
  44     QCString doc;
  45     int      line;
  46     QCString file;
  47 };
  48
  49 /** Data associated with a brief description. */
  50 struct BriefInfo
  51 {
  52     QCString doc;
  53     QCString tooltip;
  54     int      line;
  55     QCString file;
  56 };
  57
  58 /** Data associated with description found in the body. */
  59 struct BodyInfo
  60 {
  61     int      startLine;   //!< line number of the start of the definition
  62     int      endLine;     //!< line number of the end of the definition
  63     FileDef *fileDef;     //!< file definition containing the function body
  64 };
  65
  66 /** Abstract interface for a Definition or DefinitionList */
  67 class DefinitionIntf
  68 {
  69   public:
  70     DefinitionIntf() {}
  71     virtual ~DefinitionIntf() {}
  72     /*! Types of derived classes */
  73     enum DefType
  74     {
  75       TypeClass      = 0,
  76       TypeFile       = 1,
  77       TypeNamespace  = 2,
  78       TypeMember     = 3,
  79       TypeGroup      = 4,
  80       TypePackage    = 5,
  81       TypePage       = 6,
  82       TypeDir        = 7,
  83       TypeSymbolList = 8
  84     };
  85     /*! Use this for dynamic inspection of the type of the derived class */
  86     virtual DefType definitionType() const = 0;
  87 };
  88
  89 /** The common base class of all entity definitions found in the sources.
  90  *
  91  *  This can be a class or a member function, or a file, or a namespace, etc.
  92  *  Use definitionType() to find which type of definition this is.
  93  */
  94 class Definition : public DefinitionIntf, public LockableObj
  95 {
  96   public:
  97
  98     /*! Create a new definition */
  99     Definition(
 100         const char *defFileName,int defLine,
 101         const char *name,const char *b=0,const char *d=0,
 102         bool isSymbol=TRUE);
 103
 104     /*! Destroys the definition */
 105     virtual ~Definition();
 106
 107     //-----------------------------------------------------------------------------------
 108     // ----  getters -----
 109     //-----------------------------------------------------------------------------------
 110
 111     /*! Returns the name of the definition */
 112     const QCString& name() const { return m_name; }
 113
 114     /*! Returns the name of the definition as it appears in the output */
 115     virtual QCString displayName(bool includeScope=TRUE) const = 0;
 116
 117     /*! Returns the local name without any scope qualifiers. */
 118     QCString localName() const;
 119
 120     /*! Returns the fully qualified name of this definition
 121      */
 122     virtual QCString qualifiedName() const;
 123
 124     /*! Returns the name of this definition as it appears in the symbol map.
 125      */
 126     QCString symbolName() const;
 127
 128     /*! Returns the base file name (without extension) of this definition.
 129      *  as it is referenced to/written to disk.
 130      */
 131     virtual QCString getOutputFileBase() const = 0;
 132
 133     /*! Returns the anchor within a page where this item can be found */
 134     virtual QCString anchor() const = 0;
 135
 136     /*! Returns the name of the source listing of this file. */
 137     virtual QCString getSourceFileBase() const { ASSERT(0); return "NULL"; }
 138
 139     /*! Returns the detailed description of this definition */
 140     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     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 TRUE iff the definition is documented
 186      *  (which could be generated documentation)
 187      *  @see hasUserDocumentation()
 188      */
 189     virtual bool hasDocumentation() const;
 190
 191     /*! Returns TRUE iff the definition is documented by the user. */
 192     virtual bool hasUserDocumentation() const;
 193
 194     /*! Returns TRUE iff it is possible to link to this item within this
 195      *  project.
 196      */
 197     virtual bool isLinkableInProject() const = 0;
 198
 199     /*! Returns TRUE iff it is possible to link to this item. This can
 200      *  be a link to another project imported via a tag file.
 201      */
 202     virtual bool isLinkable() const = 0;
 203
 204     /*! Returns TRUE iff the name is part of this project and
 205      *  may appear in the output
 206      */
 207     virtual bool isVisibleInProject() const;
 208
 209     /*! Returns TRUE iff the name may appear in the output */
 210     virtual bool isVisible() const;
 211
 212     /*! Returns TRUE iff this item is supposed to be hidden from the output. */
 213     bool isHidden() const;
 214
 215     /*! returns TRUE if this entity was artificially introduced, for
 216      *  instance because it is used to show a template instantiation relation.
 217      */
 218     bool isArtificial() const;
 219
 220     /*! If this definition was imported via a tag file, this function
 221      *  returns the tagfile for the external project. This can be
 222      *  translated into an external link target via
 223      *  Doxygen::tagDestinationDict
 224      */
 225     virtual QCString getReference() const;
 226
 227     /*! Returns TRUE if this definition is imported via a tag file. */
 228     virtual bool isReference() const;
 229
 230     /*! Returns the first line of the body of this item (applicable to classes and
 231      *  functions).
 232      */
 233     int getStartBodyLine() const;
 234
 235     /*! Returns the last line of the body of this item (applicable to classes and
 236      *  functions).
 237      */
 238     int getEndBodyLine() const;
 239
 240     /*! Returns the file in which the body of this item is located or 0 if no
 241      *  body is available.
 242      */
 243     FileDef *getBodyDef();
 244
 245     /** Returns the programming language this definition was written in. */
 246     SrcLangExt getLanguage() const;
 247
 248     LockingPtr<GroupList> partOfGroups() const;
 249
 250     LockingPtr< QList<ListItemInfo> > xrefListItems() const;
 251
 252     virtual Definition *findInnerCompound(const char *name);
 253     virtual Definition *getOuterScope() const;
 254
 255     LockingPtr<MemberSDict> getReferencesMembers() const;
 256     LockingPtr<MemberSDict> getReferencedByMembers() const;
 257
 258     bool hasSections() const;
 259
 260     //-----------------------------------------------------------------------------------
 261     // ----  setters -----
 262     //-----------------------------------------------------------------------------------
 263
 264     /*! Sets a new \a name for the definition */
 265     void setName(const char *name);
 266
 267     /*! Sets the documentation of this definition to \a d. */
 268     virtual void setDocumentation(const char *d,const char *docFile,int docLine,bool stripWhiteSpace=TRUE);
 269
 270     /*! Sets the brief description of this definition to \a b.
 271      *  A dot is added to the sentence if not available.
 272      */
 273     virtual void setBriefDescription(const char *b,const char *briefFile,int briefLine);
 274
 275     /*! Set the documentation that was found inside the body of an item.
 276      *  If there was already some documentation set, the new documentation
 277      *  will be appended.
 278      */
 279     virtual void setInbodyDocumentation(const char *d,const char *docFile,int docLine);
 280
 281     /*! Sets the tag file id via which this definition was imported. */
 282     void setReference(const char *r);
 283
 284     /*! Add the list of anchors that mark the sections that are found in the
 285      * documentation.
 286      */
 287     void addSectionsToDefinition(QList<SectionInfo> *anchorList);
 288
 289     // source references
 290     void setBodySegment(int bls,int ble);
 291     void setBodyDef(FileDef *fd);
 292     void addSourceReferencedBy(MemberDef *d);
 293     void addSourceReferences(MemberDef *d);
 294
 295     void setRefItems(const QList<ListItemInfo> *sli);
 296     void mergeRefItems(Definition *d);
 297     virtual void addInnerCompound(Definition *d);
 298     virtual void setOuterScope(Definition *d);
 299
 300     virtual void setHidden(bool b);
 301
 302     void setArtificial(bool b);
 303     void setLanguage(SrcLangExt lang);
 304
 305     //-----------------------------------------------------------------------------------
 306     // --- actions ----
 307     //-----------------------------------------------------------------------------------
 308
 309     QCString convertNameToFile(const char *name,bool allowDots=FALSE) const;
 310     void writeSourceDef(OutputList &ol,const char *scopeName);
 311     void writeInlineCode(OutputList &ol,const char *scopeName);
 312     void writeSourceRefs(OutputList &ol,const char *scopeName);
 313     void writeSourceReffedBy(OutputList &ol,const char *scopeName);
 314     void makePartOfGroup(GroupDef *gd);
 315     //void writePathFragment(OutputList &ol) const;
 316     void writeNavigationPath(OutputList &ol) const;
 317     QCString navigationPathAsString() const;
 318     virtual void writeQuickMemberLinks(OutputList &,MemberDef *) const {}
 319     virtual void writeSummaryLinks(OutputList &) {}
 320     QCString pathFragment() const;
 321
 322     /*! Writes the documentation anchors of the definition to
 323      *  the Doxygen::tagFile stream.
 324      */
 325     void writeDocAnchorsToTagFile();
 326     void setLocalName(const QCString name);
 327
 328     void addSectionsToIndex();
 329     void writeToc(OutputList &ol);
 330
 331   protected:
 332
 333     virtual void flushToDisk() const;
 334     virtual void loadFromDisk() const;
 335     virtual void makeResident() const;
 336     void lock() const {}
 337     void unlock() const {}
 338
 339     Definition(const Definition &d);
 340
 341   private:
 342     static void addToMap(const char *name,Definition *d);
 343     static void removeFromMap(Definition *d);
 344
 345     void _setSymbolName(const QCString &name);
 346
 347     int  _getXRefListId(const char *listName) const;
 348     void _writeSourceRefList(OutputList &ol,const char *scopeName,
 349                        const QCString &text,MemberSDict *members,bool);
 350     void _setBriefDescription(const char *b,const char *briefFile,int briefLine);
 351     void _setDocumentation(const char *d,const char *docFile,int docLine,bool stripWhiteSpace,bool atTop);
 352     void _setInbodyDocumentation(const char *d,const char *docFile,int docLine);
 353     bool _docsAlreadyAdded(const QCString &doc);
 354     DefinitionImpl *m_impl; // internal structure holding all private data
 355     QCString m_name;
 356     bool m_isSymbol;
 357     QCString m_symbolName;
 358     int m_defLine;
 359 };
 360
 361 /** A list of Definition objects. */
 362 class DefinitionList : public QList<Definition>, public DefinitionIntf
 363 {
 364   public:
 365     ~DefinitionList() {}
 366     DefType definitionType() const { return TypeSymbolList; }
 367     int compareItems(GCI item1,GCI item2)
 368     {
 369       return stricmp(((Definition *)item1)->name(),
 370                      ((Definition *)item2)->name()
 371                     );
 372     }
 373
 374 };
 375
 376 /** An iterator for Definition objects in a DefinitionList. */
 377 class DefinitionListIterator : public QListIterator<Definition>
 378 {
 379   public:
 380     DefinitionListIterator(const DefinitionList &l) :
 381       QListIterator<Definition>(l) {}
 382     ~DefinitionListIterator() {}
 383 };
 384
 385 #endif