Logo ROOT  
Reference Guide
No Matches
Go to the documentation of this file.
1// @(#)root/html:$Id$
2// Author: Axel Naumann 2007-01-09
5 * Copyright (C) 1995-2007, Rene Brun and Fons Rademakers. *
6 * All rights reserved. *
7 * *
8 * For the licensing terms see $ROOTSYS/LICENSE. *
9 * For the list of contributors see $ROOTSYS/README/CREDITS. *
10 *************************************************************************/
12#ifndef ROOT_TDocParser
13#define ROOT_TDocParser
16// //
17// TDocParser //
18// //
19// Parses documentation in source files //
20// //
23#include <list>
24#include <set>
25#include <map>
27#include "TObject.h"
28#include "THashList.h"
29#include "TString.h"
31class TBaseClass;
32class TClass;
33class TClassDocOutput;
34class TDocOutput;
35class THtml;
39 virtual TMethod* GetMethod() const = 0;
40 virtual Int_t GetOverloadIdx() const = 0;
41 enum { kDocumented = 14 };
44class TDocParser: public TObject {
51 };
61 };
62 enum EAccess {
66 };
77 kParseContextMask = BIT(4) - 1
78 };
80 kCXXComment = BIT(4), // kComment is a C++ comment, or macro/html/latex content is surrounded by /* */
81 kParseContextFlagMask = (UInt_t)(~(BIT(4) - 1))
83 };
86 THtml* fHtml; // THtml object using us
87 TDocOutput* fDocOutput; // TDocOutput invoking us
88 UInt_t fLineNo; // current line number
89 TString fLineRaw; // current line
90 TString fLineStripped; // current line without surrounding spaces
91 TString fLineComment; // current line with links and directives for doc
92 TString fLineSource; // current line with links
93 TString fComment; // current comment
94 TString fFirstClassDoc; // first class-doc found - per file, taken if fLastClassDoc is empty
95 TString fLastClassDoc; // last class-doc found - becomes class doc at ClassImp or first method
96 TClass* fCurrentClass; // current class context of sources being parsed
97 TClass* fRecentClass; // recently seen class context of sources being parsed, e.g. for Convert()
98 TString fCurrentModule; // current module context of sources being parsed
99 TString fCurrentMethodTag;// name_idx of the currently parsed method
100 Int_t fDirectiveCount; // index of directive for current method
101 Long_t fLineNumber; // source line number
102 TString fCurrentFile; // current source / header file name
103 std::map<std::string /*name*/, Int_t > fMethodCounts; // number of undocumented overloads
104 EDocContext fDocContext; // current context of parsed sources for documenting
105 std::list<UInt_t> fParseContext; // current context of parsed sources
106 Bool_t fCheckForMethod; // whether to check the current line for a method
107 enum {
114 } fClassDocState; // whether we found the class description
115 Bool_t fCommentAtBOL; // at the beginning of the current line, fParseContext contained kComment
116 TString fClassDescrTag; // tag for finding the class description
117 TString fSourceInfoTags[kNumSourceInfos]; // tags for source info elements (copyright, last changed, author)
118 TList fDirectiveHandlers;// handler for doc directives (TDocDirective objects)
119 Bool_t fAllowDirectives; // whether directives are to be interpreted
120 std::set<UInt_t> fExtraLinesWithAnchor; // lines that need an additional anchor
121 TString fSourceInfo[kNumSourceInfos];// author, last changed, ...
122 THashList fMethods[3]; // methods as TMethodWrapper objects (by access)
123 TList fDataMembers[6]; // data members (by access, plus enums)
125 static std::set<std::string> fgKeywords; // C++ keywords
130 virtual void ExpandCPPLine(TString& line, Ssiz_t& pos);
131 virtual Bool_t HandleDirective(TString& keyword, Ssiz_t& pos,
132 TString& word, Ssiz_t& copiedToCommentUpTo);
133 void InitKeywords() const;
134 virtual TClass* IsDirective(const TString& line, Ssiz_t pos, const TString& word, Bool_t& begin) const;
135 TMethod* LocateMethodInCurrentLine(Ssiz_t& posMethodName, TString& ret,
136 TString& name, TString& params, Bool_t& isconst,
137 std::ostream &srcOut, TString &anchor,
138 std::ifstream& sourcefile, Bool_t allowPureVirtual);
139 void LocateMethodsInSource(std::ostream& out);
140 void LocateMethodsInHeaderInline(std::ostream& out);
141 void LocateMethodsInHeaderClassDecl(std::ostream& out);
142 void LocateMethods(std::ostream& out, const char* filename,
143 Bool_t lookForSourceInfo = kTRUE,
144 Bool_t useDocxxStyle = kFALSE,
145 Bool_t allowPureVirtual = kFALSE,
146 const char* methodPattern = 0,
147 const char* sourceExt = 0);
148 virtual Bool_t ProcessComment();
149 void RemoveCommentContext(Bool_t cxxcomment);
150 void WriteClassDoc(std::ostream& out, Bool_t first = kTRUE);
151 void WriteMethod(std::ostream& out, TString& ret,
152 TString& name, TString& params,
153 Bool_t isconst,
154 const char* file, TString& anchor,
155 TString& codeOneLiner);
156 void WriteSourceLine(std::ostream& out);
159 TDocParser(TClassDocOutput& docOutput, TClass* cl);
160 TDocParser(TDocOutput& docOutput);
161 ~TDocParser() override;
163 static void AnchorFromLine(const TString& line, TString& anchor);
164 void Convert(std::ostream& out, std::istream& in, const char* relpath,
165 Bool_t isCode, Bool_t interpretDirectives);
166 void DecrementMethodCount(const char* name);
167 virtual void DecorateKeywords(std::ostream& out, const char* text);
168 virtual void DecorateKeywords(TString& text);
169 virtual void DeleteDirectiveOutput() const;
170 const TList* GetMethods(EAccess access) const { return &fMethods[access]; }
172 void GetCurrentModule(TString& out_module) const;
173 TDocOutput* GetDocOutput() const { return fDocOutput; }
174 Long_t GetLineNumber() const { return fLineNumber; }
175 const TList* GetDataMembers(EAccess access) const { return &fDataMembers[access]; }
176 const TList* GetEnums(EAccess access) const { return &fDataMembers[access+3]; }
177 const char* GetSourceInfo(ESourceInfo type) const { return fSourceInfo[type]; }
178 void SetCurrentModule(const char* module) { fCurrentModule = module; }
180 UInt_t InContext(Int_t context) const;
181 static Bool_t IsName(UChar_t c);
182 static Bool_t IsWord(UChar_t c);
184 virtual void Parse(std::ostream& out);
185 static Bool_t Strip(TString& s);
187 ClassDefOverride(TDocParser,0); // parser for reference documentation
190#endif // ROOT_TDocParser
#define c(i)
Definition RSha256.hxx:101
bool Bool_t
Definition RtypesCore.h:63
int Int_t
Definition RtypesCore.h:45
unsigned char UChar_t
Definition RtypesCore.h:38
int Ssiz_t
Definition RtypesCore.h:67
long Long_t
Definition RtypesCore.h:54
unsigned int UInt_t
Definition RtypesCore.h:46
constexpr Bool_t kFALSE
Definition RtypesCore.h:101
constexpr Bool_t kTRUE
Definition RtypesCore.h:100
#define BIT(n)
Definition Rtypes.h:85
#define ClassDefOverride(name, id)
Definition Rtypes.h:341
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void char Point_t Rectangle_t WindowAttributes_t Float_t Float_t Float_t Int_t Int_t UInt_t UInt_t Rectangle_t Int_t Int_t Window_t TString Int_t GCValues_t GetPrimarySelectionOwner GetDisplay GetScreen GetColormap GetNativeEvent const char const char dpyName wid window const char font_name cursor keysym reg const char only_if_exist regb h Point_t winding char text const char depth char const char Int_t count const char ColorStruct_t color const char filename
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void char Point_t Rectangle_t WindowAttributes_t Float_t Float_t Float_t Int_t Int_t UInt_t UInt_t Rectangle_t Int_t Int_t Window_t TString Int_t GCValues_t GetPrimarySelectionOwner GetDisplay GetScreen GetColormap GetNativeEvent const char const char dpyName wid window const char font_name cursor keysym reg const char only_if_exist regb h Point_t winding char text const char depth char const char Int_t count const char ColorStruct_t color const char Pixmap_t Pixmap_t PictureAttributes_t attr const char char ret_data h unsigned char height h Atom_t Int_t ULong_t ULong_t unsigned char prop_list Atom_t Atom_t Atom_t Time_t type
Option_t Option_t TPoint TPoint const char text
char name[80]
Definition TGX11.cxx:110
Each class (see TClass) has a linked list of its base class(es).
Definition TBaseClass.h:33
TClass instances represent classes, structs and namespaces in the ROOT type system.
Definition TClass.h:81
virtual Int_t GetOverloadIdx() const =0
virtual TMethod * GetMethod() const =0
static void AnchorFromLine(const TString &line, TString &anchor)
Create an anchor from the given line, by hashing it and convertig the hash into a custom base64 strin...
static Bool_t IsWord(UChar_t c)
Check if c is a valid first character for C++ name.
EParseContext Context() const
Definition TDocParser.h:129
EDocContext fDocContext
Definition TDocParser.h:104
void LocateMethodsInSource(std::ostream &out)
Given fCurrentClass, look for methods in its source file, and extract documentation to out,...
void WriteClassDoc(std::ostream &out, Bool_t first=kTRUE)
Write the class description depending (among others) on fClassDocState.
TString fCurrentFile
Definition TDocParser.h:102
~TDocParser() override
destructor, checking whether all methods have been found for gDebug > 3
TString fCurrentModule
Definition TDocParser.h:98
std::set< UInt_t > fExtraLinesWithAnchor
Definition TDocParser.h:120
const TList * GetMethods(EAccess access) const
Definition TDocParser.h:170
const char * GetSourceInfo(ESourceInfo type) const
Definition TDocParser.h:177
void LocateMethodsInHeaderClassDecl(std::ostream &out)
Given fCurrentClass, look for methods in its header file's class declaration block,...
virtual void ExpandCPPLine(TString &line, Ssiz_t &pos)
Expand preprocessor statements.
Long_t fLineNumber
Definition TDocParser.h:101
THtml * fHtml
Definition TDocParser.h:86
void SetCurrentModule(const char *module)
Definition TDocParser.h:178
@ kNumParseContexts
Definition TDocParser.h:76
@ kParseContextMask
Definition TDocParser.h:77
TString fComment
Definition TDocParser.h:93
TClass * fRecentClass
Definition TDocParser.h:97
const TList * GetDataMembers(EAccess access) const
Definition TDocParser.h:175
void LocateMethodsInHeaderInline(std::ostream &out)
Given fCurrentClass, look for methods in its header file, and extract documentation to out.
@ kClassDoc_NumStates
Definition TDocParser.h:113
@ kClassDoc_Uninitialized
Definition TDocParser.h:108
@ kClassDoc_Written
Definition TDocParser.h:111
@ kClassDoc_LookingNothingFound
Definition TDocParser.h:109
@ kClassDoc_LookingHaveSomething
Definition TDocParser.h:110
virtual TClass * IsDirective(const TString &line, Ssiz_t pos, const TString &word, Bool_t &begin) const
return whether word at line's pos is a valid directive, and returns its TDocDirective's TClass object...
TList fDirectiveHandlers
Definition TDocParser.h:118
static Bool_t Strip(TString &s)
strips ' ', tabs, and newlines from both sides of str
void WriteMethod(std::ostream &out, TString &ret, TString &name, TString &params, Bool_t isconst, const char *file, TString &anchor, TString &codeOneLiner)
Write a method, forwarding to TClassDocOutput.
TMethod * LocateMethodInCurrentLine(Ssiz_t &posMethodName, TString &ret, TString &name, TString &params, Bool_t &isconst, std::ostream &srcOut, TString &anchor, std::ifstream &sourcefile, Bool_t allowPureVirtual)
Search for a method starting at posMethodName, and return its return type, its name,...
TClass * fCurrentClass
Definition TDocParser.h:96
void InitKeywords() const
fill C++ keywords into fgKeywords
void RemoveCommentContext(Bool_t cxxcomment)
remove the top-most comment context that matches cxxcomment,
Bool_t fCommentAtBOL
Definition TDocParser.h:115
TString fSourceInfoTags[kNumSourceInfos]
Definition TDocParser.h:117
@ kParseContextFlagMask
Definition TDocParser.h:81
TString fLineSource
Definition TDocParser.h:92
@ kNumDocContexts
Definition TDocParser.h:50
TString fCurrentMethodTag
Definition TDocParser.h:99
TString fSourceInfo[kNumSourceInfos]
Definition TDocParser.h:121
void DecrementMethodCount(const char *name)
reduce method count for method called name, removing it from fMethodCounts once the count reaches 0.
virtual Bool_t ProcessComment()
Parse the current line as a comment, handling directives and re-formatting the comment: remove "/*",...
Bool_t fAllowDirectives
Definition TDocParser.h:119
static Bool_t IsName(UChar_t c)
Check if c is a valid C++ name character.
UInt_t fLineNo
Definition TDocParser.h:88
@ kInfoLastChanged
Definition TDocParser.h:58
@ kNumSourceInfos
Definition TDocParser.h:60
@ kInfoLastUpdate
Definition TDocParser.h:55
@ kInfoLastGenerated
Definition TDocParser.h:59
Long_t GetLineNumber() const
Definition TDocParser.h:174
void GetCurrentModule(TString &out_module) const
Return the name of module for which sources are currently parsed.
void Convert(std::ostream &out, std::istream &in, const char *relpath, Bool_t isCode, Bool_t interpretDirectives)
Parse text file "in", add links etc, and write output to "out".
void LocateMethods(std::ostream &out, const char *filename, Bool_t lookForSourceInfo=kTRUE, Bool_t useDocxxStyle=kFALSE, Bool_t allowPureVirtual=kFALSE, const char *methodPattern=0, const char *sourceExt=0)
Collect methods from the source or header file called filename.
TString fFirstClassDoc
Definition TDocParser.h:94
TDocOutput * GetDocOutput() const
Definition TDocParser.h:173
enum TDocParser::@99 fClassDocState
std::list< UInt_t > fParseContext
Definition TDocParser.h:105
THashList fMethods[3]
Definition TDocParser.h:122
Bool_t fCheckForMethod
Definition TDocParser.h:106
UInt_t InContext(Int_t context) const
checks whether we are in a parse context, return the entry closest to the current context.
void AddClassMethodsRecursively(TBaseClass *bc)
Add accessible (i.e.
const TList * GetEnums(EAccess access) const
Definition TDocParser.h:176
TDocOutput * fDocOutput
Definition TDocParser.h:87
std::map< std::string, Int_t > fMethodCounts
Definition TDocParser.h:103
TString fLastClassDoc
Definition TDocParser.h:95
void WriteSourceLine(std::ostream &out)
Write fLineSource to out.
static std::set< std::string > fgKeywords
Definition TDocParser.h:125
TString fLineStripped
Definition TDocParser.h:90
void AddClassDataMembersRecursively(TBaseClass *bc)
Add data members of fCurrentClass and of bc to datamembers, recursively.
TString fLineRaw
Definition TDocParser.h:89
TString fClassDescrTag
Definition TDocParser.h:116
virtual void DecorateKeywords(std::ostream &out, const char *text)
Expand keywords in text, writing to out.
TString fLineComment
Definition TDocParser.h:91
virtual Bool_t HandleDirective(TString &keyword, Ssiz_t &pos, TString &word, Ssiz_t &copiedToCommentUpTo)
Process directives to the documentation engine, like "Begin_Html" / "End_Html", "Begin_Macro" / "End_...
virtual void DeleteDirectiveOutput() const
Delete output generated by prior runs of all known directives; the output file names might have chang...
TClass * GetCurrentClass() const
Definition TDocParser.h:171
Int_t fDirectiveCount
Definition TDocParser.h:100
virtual void Parse(std::ostream &out)
Locate methods, starting in the source file, then inline, then immediately inside the class declarati...
TList fDataMembers[6]
Definition TDocParser.h:123
THashList implements a hybrid collection class consisting of a hash table and a list to store TObject...
Definition THashList.h:34
Legacy ROOT documentation system.
Definition THtml.h:40
A doubly linked list.
Definition TList.h:38
Each ROOT class (see TClass) has a linked list of methods.
Definition TMethod.h:38
Mother of all ROOT objects.
Definition TObject.h:41
Basic string class.
Definition TString.h:139
TLine * line