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