/******************************************************************************
*
*
*
* Copyright (C) 1997-2015 by Dimitri van Heesch.
*
* Permission to use, copy, modify, and distribute this software and its
* documentation under the terms of the GNU General Public License is hereby
* granted. No representations are made about the suitability of this software
* for any purpose. It is provided "as is" without express or implied warranty.
* See the GNU General Public License for more details.
*
* Documents produced by Doxygen are derivative works derived from the
* input used in their production; they are not affected by this license.
*
*/
#ifndef DEFINITION_H
#define DEFINITION_H
#include <qlist.h>
#include <qdict.h>
#include "types.h"
class FileDef;
class OutputList;
class SectionDict;
class MemberSDict;
class MemberDef;
class GroupDef;
class GroupList;
struct ListItemInfo;
struct SectionInfo;
class Definition;
class DefinitionImpl;
class FTextStream;
/** Data associated with a detailed description. */
struct DocInfo
{
QCString doc;
int line;
QCString file;
};
/** Data associated with a brief description. */
struct BriefInfo
{
QCString doc;
QCString tooltip;
int line;
QCString file;
};
/** Data associated with description found in the body. */
struct BodyInfo
{
int startLine; //!< line number of the start of the definition
int endLine; //!< line number of the end of the definition
FileDef *fileDef; //!< file definition containing the function body
};
/** Abstract interface for a Definition or DefinitionList */
class DefinitionIntf
{
public:
DefinitionIntf() {}
virtual ~DefinitionIntf() {}
/*! Types of derived classes */
enum DefType
{
TypeClass = 0,
TypeFile = 1,
TypeNamespace = 2,
TypeMember = 3,
TypeGroup = 4,
TypePackage = 5,
TypePage = 6,
TypeDir = 7,
TypeSymbolList = 8
};
/*! Use this for dynamic inspection of the type of the derived class */
virtual DefType definitionType() const = 0;
};
/** The common base class of all entity definitions found in the sources.
*
* This can be a class or a member function, or a file, or a namespace, etc.
* Use definitionType() to find which type of definition this is.
*/
class Definition : public DefinitionIntf
{
public:
struct Cookie
{
virtual ~Cookie() {}
};
/*! Create a new definition */
Definition(
const char *defFileName,int defLine,int defColumn,
const char *name,const char *b=0,const char *d=0,
bool isSymbol=TRUE);
/*! Destroys the definition */
virtual ~Definition();
//-----------------------------------------------------------------------------------
// ---- getters -----
//-----------------------------------------------------------------------------------
/*! Returns the name of the definition */
const QCString& name() const { return m_name; }
/*! Returns the name of the definition as it appears in the output */
virtual QCString displayName(bool includeScope=TRUE) const = 0;
/*! Returns the local name without any scope qualifiers. */
QCString localName() const;
/*! Returns the fully qualified name of this definition
*/
virtual QCString qualifiedName() const;
/*! Returns the name of this definition as it appears in the symbol map.
*/
QCString symbolName() const;
/*! Returns the base file name (without extension) of this definition.
* as it is referenced to/written to disk.
*/
virtual QCString getOutputFileBase() const = 0;
/*! Returns the anchor within a page where this item can be found */
virtual QCString anchor() const = 0;
/*! Returns the name of the source listing of this definition. */
virtual QCString getSourceFileBase() const;
/*! Returns the anchor of the source listing of this definition. */
virtual QCString getSourceAnchor() const;
/*! Returns the detailed description of this definition */
virtual QCString documentation() const;
/*! Returns the line number at which the detailed documentation was found. */
int docLine() const;
/*! Returns the file in which the detailed documentation block was found.
* This can differ from getDefFileName().
*/
QCString docFile() const;
/*! Returns the brief description of this definition. This can include commands. */
virtual QCString briefDescription(bool abbreviate=FALSE) const;
/*! Returns a plain text version of the brief description suitable for use
* as a tool tip.
*/
QCString briefDescriptionAsTooltip() const;
/*! Returns the line number at which the brief description was found. */
int briefLine() const;
/*! Returns the documentation found inside the body of a member */
QCString inbodyDocumentation() const;
/*! Returns the file in which the in body documentation was found */
QCString inbodyFile() const;
/*! Returns the line at which the first in body documentation
part was found */
int inbodyLine() const;
/*! Returns the file in which the brief description was found.
* This can differ from getDefFileName().
*/
QCString briefFile() const;
/*! returns the file in which this definition was found */
QCString getDefFileName() const;
/*! returns the extension of the file in which this definition was found */
QCString getDefFileExtension() const;
/*! returns the line number at which the definition was found */
int getDefLine() const { return m_defLine; }
/*! returns the column number at which the definition was found */
int getDefColumn() const { return m_defColumn; }
/*! Returns TRUE iff the definition is documented
* (which could be generated documentation)
* @see hasUserDocumentation()
*/
virtual bool hasDocumentation() const;
/*! Returns TRUE iff the definition is documented by the user. */
virtual bool hasUserDocumentation() const;
/*! Returns TRUE iff it is possible to link to this item within this
* project.
*/
virtual bool isLinkableInProject() const = 0;
/*! Returns TRUE iff it is possible to link to this item. This can
* be a link to another project imported via a tag file.
*/
virtual bool isLinkable() const = 0;
/*! Returns TRUE iff the name is part of this project and
* may appear in the output
*/
virtual bool isVisibleInProject() const;
/*! Returns TRUE iff the name may appear in the output */
virtual bool isVisible() const;
/*! Returns TRUE iff this item is supposed to be hidden from the output. */
bool isHidden() const;
/*! returns TRUE if this entity was artificially introduced, for
* instance because it is used to show a template instantiation relation.
*/
bool isArtificial() const;
/*! If this definition was imported via a tag file, this function
* returns the tagfile for the external project. This can be
* translated into an external link target via
* Doxygen::tagDestinationDict
*/
virtual QCString getReference() const;
/*! Returns TRUE if this definition is imported via a tag file. */
virtual bool isReference() const;
/*! Convenience method to return a resolved external link */
QCString externalReference(const QCString &relPath) const;
/*! Returns the first line of the body of this item (applicable to classes and
* functions).
*/
int getStartBodyLine() const;
/*! Returns the last line of the body of this item (applicable to classes and
* functions).
*/
int getEndBodyLine() const;
/*! Returns the file in which the body of this item is located or 0 if no
* body is available.
*/
FileDef *getBodyDef() const;
/** Returns the programming language this definition was written in. */
SrcLangExt getLanguage() const;
GroupList *partOfGroups() const;
bool isLinkableViaGroup() const;
QList<ListItemInfo> *xrefListItems() const;
virtual Definition *findInnerCompound(const char *name) const ;
virtual Definition *getOuterScope() const;
MemberSDict *getReferencesMembers() const;
MemberSDict *getReferencedByMembers() const;
bool hasSections() const;
bool hasSources() const;
/** returns TRUE if this class has a brief description */
bool hasBriefDescription() const;
QCString id() const;
//-----------------------------------------------------------------------------------
// ---- setters -----
//-----------------------------------------------------------------------------------
/*! Sets a new \a name for the definition */
virtual void setName(const char *name);
/*! Sets a unique id for the symbol. Used for libclang integration. */
void setId(const char *name);
/*! Sets the documentation of this definition to \a d. */
virtual void setDocumentation(const char *d,const char *docFile,int docLine,bool stripWhiteSpace=TRUE);
/*! Sets the brief description of this definition to \a b.
* A dot is added to the sentence if not available.
*/
virtual void setBriefDescription(const char *b,const char *briefFile,int briefLine);
/*! Set the documentation that was found inside the body of an item.
* If there was already some documentation set, the new documentation
* will be appended.
*/
virtual void setInbodyDocumentation(const char *d,const char *docFile,int docLine);
/*! Sets the tag file id via which this definition was imported. */
void setReference(const char *r);
/*! Add the list of anchors that mark the sections that are found in the
* documentation.
*/
void addSectionsToDefinition(QList<SectionInfo> *anchorList);
// source references
void setBodySegment(int bls,int ble);
void setBodyDef(FileDef *fd);
void addSourceReferencedBy(MemberDef *d);
void addSourceReferences(MemberDef *d);
void setRefItems(const QList<ListItemInfo> *sli);
void mergeRefItems(Definition *d);
virtual void addInnerCompound(Definition *d);
virtual void setOuterScope(Definition *d);
virtual void setHidden(bool b);
void setArtificial(bool b);
void setLanguage(SrcLangExt lang);
//-----------------------------------------------------------------------------------
// --- actions ----
//-----------------------------------------------------------------------------------
void writeSourceDef(OutputList &ol,const char *scopeName);
void writeInlineCode(OutputList &ol,const char *scopeName);
void writeSourceRefs(OutputList &ol,const char *scopeName);
void writeSourceReffedBy(OutputList &ol,const char *scopeName);
void makePartOfGroup(GroupDef *gd);
//void writePathFragment(OutputList &ol) const;
void writeNavigationPath(OutputList &ol) const;
QCString navigationPathAsString() const;
virtual void writeQuickMemberLinks(OutputList &,MemberDef *) const {}
virtual void writeSummaryLinks(OutputList &) {}
QCString pathFragment() const;
/*! Writes the documentation anchors of the definition to
* the Doxygen::tagFile stream.
*/
void writeDocAnchorsToTagFile(FTextStream &);
void setLocalName(const QCString name);
void addSectionsToIndex();
void writeToc(OutputList &ol);
void setCookie(Cookie *cookie) { delete m_cookie; m_cookie = cookie; }
Cookie *cookie() const { return m_cookie; }
protected:
Definition(const Definition &d);
private:
static void addToMap(const char *name,Definition *d);
static void removeFromMap(Definition *d);
void _setSymbolName(const QCString &name);
int _getXRefListId(const char *listName) const;
void _writeSourceRefList(OutputList &ol,const char *scopeName,
const QCString &text,MemberSDict *members,bool);
void _setBriefDescription(const char *b,const char *briefFile,int briefLine);
void _setDocumentation(const char *d,const char *docFile,int docLine,bool stripWhiteSpace,bool atTop);
void _setInbodyDocumentation(const char *d,const char *docFile,int docLine);
bool _docsAlreadyAdded(const QCString &doc,QCString &sigList);
DefinitionImpl *m_impl; // internal structure holding all private data
QCString m_name;
bool m_isSymbol;
QCString m_symbolName;
int m_defLine;
int m_defColumn;
Cookie *m_cookie;
};
/** A list of Definition objects. */
class DefinitionList : public QList<Definition>, public DefinitionIntf
{
public:
~DefinitionList() {}
DefType definitionType() const { return TypeSymbolList; }
int compareValues(const Definition *item1,const Definition *item2) const
{
return qstricmp(item1->name(),item2->name());
}
};
/** An iterator for Definition objects in a DefinitionList. */
class DefinitionListIterator : public QListIterator<Definition>
{
public:
DefinitionListIterator(const DefinitionList &l) :
QListIterator<Definition>(l) {}
~DefinitionListIterator() {}
};
/** Reads a fragment from file \a fileName starting with line \a startLine
* and ending with line \a endLine. The result is returned as a string
* via \a result. The function returns TRUE if successful and FALSE
* in case of an error.
*/
bool readCodeFragment(const char *fileName,
int &startLine,int &endLine,
QCString &result);
#endif