Logo ROOT  
Reference Guide
TDocParser.h
Go to the documentation of this file.
1 // @(#)root/html:$Id$
2 // Author: Axel Naumann 2007-01-09
3 
4 /*************************************************************************
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  *************************************************************************/
11 
12 #ifndef ROOT_TDocParser
13 #define ROOT_TDocParser
14 
15 ////////////////////////////////////////////////////////////////////////////
16 // //
17 // TDocParser //
18 // //
19 // Parses documentation in source files //
20 // //
21 ////////////////////////////////////////////////////////////////////////////
22 
23 #include <list>
24 #include <set>
25 #include <map>
26 
27 #include "TObject.h"
28 #include "THashList.h"
29 #include "TString.h"
30 
31 class TBaseClass;
32 class TClass;
33 class TClassDocOutput;
34 class TDocOutput;
35 class THtml;
36 
37 class TDocMethodWrapper: public TObject {
38 public:
39  virtual TMethod* GetMethod() const = 0;
40  virtual Int_t GetOverloadIdx() const = 0;
41  enum { kDocumented = 14 };
42 };
43 
44 class TDocParser: public TObject {
45 protected:
46  enum EDocContext {
51  };
52 
53 public:
54  enum ESourceInfo {
61  };
62  enum EAccess {
65  kPublic
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))
82 
83  };
84 
85 protected:
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)
124 
125  static std::set<std::string> fgKeywords; // C++ keywords
126 
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  virtual 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);
157 
158 public:
159  TDocParser(TClassDocOutput& docOutput, TClass* cl);
160  TDocParser(TDocOutput& docOutput);
161  virtual ~TDocParser();
162 
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]; }
171  TClass* GetCurrentClass() const { return fCurrentClass; }
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; }
179 
180  UInt_t InContext(Int_t context) const;
181  static Bool_t IsName(UChar_t c);
182  static Bool_t IsWord(UChar_t c);
183 
184  virtual void Parse(std::ostream& out);
185  static Bool_t Strip(TString& s);
186 
187  ClassDef(TDocParser,0); // parser for reference documentation
188 };
189 
190 #endif // ROOT_TDocParser
c
#define c(i)
Definition: RSha256.hxx:101
TDocParser::kCXXComment
@ kCXXComment
Definition: TDocParser.h:80
TDocParser::AnchorFromLine
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...
Definition: TDocParser.cxx:381
TDocParser::kNumDocContexts
@ kNumDocContexts
Definition: TDocParser.h:50
TDocParser::HandleDirective
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_...
Definition: TDocParser.cxx:977
TDocParser::fCommentAtBOL
Bool_t fCommentAtBOL
Definition: TDocParser.h:115
TDocParser::fCurrentModule
TString fCurrentModule
Definition: TDocParser.h:98
TDocParser::fAllowDirectives
Bool_t fAllowDirectives
Definition: TDocParser.h:119
TDocParser::kString
@ kString
Definition: TDocParser.h:72
first
Definition: first.py:1
TDocParser::kInfoCopyright
@ kInfoCopyright
Definition: TDocParser.h:57
TDocParser::fExtraLinesWithAnchor
std::set< UInt_t > fExtraLinesWithAnchor
Definition: TDocParser.h:120
TDocParser::Strip
static Bool_t Strip(TString &s)
strips ' ', tabs, and newlines from both sides of str
Definition: TDocParser.cxx:2075
kTRUE
const Bool_t kTRUE
Definition: RtypesCore.h:91
TDocParser::LocateMethodsInHeaderInline
void LocateMethodsInHeaderInline(std::ostream &out)
Given fCurrentClass, look for methods in its header file, and extract documentation to out.
Definition: TDocParser.cxx:1879
TDocParser::DecorateKeywords
virtual void DecorateKeywords(std::ostream &out, const char *text)
Expand keywords in text, writing to out.
Definition: TDocParser.cxx:450
TDocParser::fFirstClassDoc
TString fFirstClassDoc
Definition: TDocParser.h:94
TDocParser::fgKeywords
static std::set< std::string > fgKeywords
Definition: TDocParser.h:125
TDocParser::LocateMethodsInHeaderClassDecl
void LocateMethodsInHeaderClassDecl(std::ostream &out)
Given fCurrentClass, look for methods in its header file's class declaration block,...
Definition: TDocParser.cxx:1913
TDocParser::kVerbatim
@ kVerbatim
Definition: TDocParser.h:75
TDocParser::fRecentClass
TClass * fRecentClass
Definition: TDocParser.h:97
TDocParser::fParseContext
std::list< UInt_t > fParseContext
Definition: TDocParser.h:105
TDocParser::kClassDoc_Written
@ kClassDoc_Written
Definition: TDocParser.h:111
TDocParser::kInfoLastChanged
@ kInfoLastChanged
Definition: TDocParser.h:58
TDocParser::fSourceInfo
TString fSourceInfo[kNumSourceInfos]
Definition: TDocParser.h:121
TDocParser::fCurrentClass
TClass * fCurrentClass
Definition: TDocParser.h:96
TDocParser::kIgnore
@ kIgnore
Definition: TDocParser.h:47
TDocParser::WriteMethod
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.
Definition: TDocParser.cxx:2242
TDocParser::kClassDoc_LookingHaveSomething
@ kClassDoc_LookingHaveSomething
Definition: TDocParser.h:110
TDocParser::GetDocOutput
TDocOutput * GetDocOutput() const
Definition: TDocParser.h:173
TDocParser::kComment
@ kComment
Definition: TDocParser.h:70
TDocParser::LocateMethods
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.
Definition: TDocParser.cxx:1607
TDocParser::kClassDoc_Ignore
@ kClassDoc_Ignore
Definition: TDocParser.h:112
TDocParser::IsName
static Bool_t IsName(UChar_t c)
Check if c is a valid C++ name character.
Definition: TDocParser.cxx:1301
TBaseClass
Each class (see TClass) has a linked list of its base class(es).
Definition: TBaseClass.h:33
TGeant4Unit::s
static constexpr double s
Definition: TGeant4SystemOfUnits.h:162
TDocParser::fDirectiveCount
Int_t fDirectiveCount
Definition: TDocParser.h:100
Int_t
int Int_t
Definition: RtypesCore.h:45
TDocParser::fLineRaw
TString fLineRaw
Definition: TDocParser.h:89
TDocParser::fMethodCounts
std::map< std::string, Int_t > fMethodCounts
Definition: TDocParser.h:103
TDocParser::kPrivate
@ kPrivate
Definition: TDocParser.h:63
TDocParser
Definition: TDocParser.h:44
TDocParser::InitKeywords
virtual void InitKeywords() const
fill C++ keywords into fgKeywords
Definition: TDocParser.cxx:1175
TDocParser::Context
EParseContext Context() const
Definition: TDocParser.h:129
TDocParser::kInfoAuthor
@ kInfoAuthor
Definition: TDocParser.h:56
TDocParser::kCPP
@ kCPP
Definition: TDocParser.h:74
TDocMethodWrapper::GetOverloadIdx
virtual Int_t GetOverloadIdx() const =0
TString
Basic string class.
Definition: TString.h:136
TDocParser::kInfoLastGenerated
@ kInfoLastGenerated
Definition: TDocParser.h:59
Bool_t
bool Bool_t
Definition: RtypesCore.h:63
TDocParser::fCurrentFile
TString fCurrentFile
Definition: TDocParser.h:102
TDocParser::fClassDocState
enum TDocParser::@92 fClassDocState
text
TText * text
Definition: entrylist_figure1.C:10
TDocParser::kNoContext
@ kNoContext
Definition: TDocParser.h:68
TDocParser::fLineComment
TString fLineComment
Definition: TDocParser.h:91
TString.h
bool
TDocParser::kDirective
@ kDirective
Definition: TDocParser.h:71
TDocParser::TDocParser
TDocParser(TClassDocOutput &docOutput, TClass *cl)
Constructor called for parsing class sources.
Definition: TDocParser.cxx:150
TDocParser::fLineStripped
TString fLineStripped
Definition: TDocParser.h:90
TDocParser::kCode
@ kCode
Definition: TDocParser.h:69
TDocParser::ESourceInfo
ESourceInfo
Definition: TDocParser.h:54
TDocParser::GetCurrentClass
TClass * GetCurrentClass() const
Definition: TDocParser.h:171
TDocParser::SetCurrentModule
void SetCurrentModule(const char *module)
Definition: TDocParser.h:178
TDocParser::kProtected
@ kProtected
Definition: TDocParser.h:64
THtml
Definition: THtml.h:40
TDocParser::fDocContext
EDocContext fDocContext
Definition: TDocParser.h:104
TDocParser::kClassDoc_NumStates
@ kClassDoc_NumStates
Definition: TDocParser.h:113
THashList
THashList implements a hybrid collection class consisting of a hash table and a list to store TObject...
Definition: THashList.h:34
TDocParser::kNumSourceInfos
@ kNumSourceInfos
Definition: TDocParser.h:60
TDocParser::AddClassMethodsRecursively
void AddClassMethodsRecursively(TBaseClass *bc)
Add accessible (i.e.
Definition: TDocParser.cxx:235
TDocParser::LocateMethodsInSource
void LocateMethodsInSource(std::ostream &out)
Given fCurrentClass, look for methods in its source file, and extract documentation to out,...
Definition: TDocParser.cxx:1846
TDocParser::kPublic
@ kPublic
Definition: TDocParser.h:65
TDocMethodWrapper
Definition: TDocParser.h:37
kFALSE
const Bool_t kFALSE
Definition: RtypesCore.h:92
TDocParser::fLineSource
TString fLineSource
Definition: TDocParser.h:92
TDocParser::EParseContextFlag
EParseContextFlag
Definition: TDocParser.h:79
TDocParser::DecrementMethodCount
void DecrementMethodCount(const char *name)
reduce method count for method called name, removing it from fMethodCounts once the count reaches 0.
Definition: TDocParser.cxx:869
TMethod
Each ROOT class (see TClass) has a linked list of methods.
Definition: TMethod.h:38
Long_t
long Long_t
Definition: RtypesCore.h:54
extract_docstrings.module
module
Definition: extract_docstrings.py:39
TDocParser::EParseContext
EParseContext
Definition: TDocParser.h:67
BIT
#define BIT(n)
Definition: Rtypes.h:85
TDocParser::GetCurrentModule
void GetCurrentModule(TString &out_module) const
Return the name of module for which sources are currently parsed.
Definition: TDocParser.cxx:967
UInt_t
unsigned int UInt_t
Definition: RtypesCore.h:46
TDocParser::fLineNumber
Long_t fLineNumber
Definition: TDocParser.h:101
TDocParser::GetDataMembers
const TList * GetDataMembers(EAccess access) const
Definition: TDocParser.h:175
line
TLine * line
Definition: entrylistblock_figure1.C:235
TDocParser::LocateMethodInCurrentLine
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,...
Definition: TDocParser.cxx:1343
TDocParser::kKeyword
@ kKeyword
Definition: TDocParser.h:73
TDocParser::DeleteDirectiveOutput
virtual void DeleteDirectiveOutput() const
Delete output generated by prior runs of all known directives; the output file names might have chang...
Definition: TDocParser.cxx:884
TDocMethodWrapper::GetMethod
virtual TMethod * GetMethod() const =0
unsigned int
TDocParser::fHtml
THtml * fHtml
Definition: TDocParser.h:86
TDocParser::RemoveCommentContext
void RemoveCommentContext(Bool_t cxxcomment)
remove the top-most comment context that matches cxxcomment,
Definition: TDocParser.cxx:2060
THashList.h
TDocOutput
Definition: TDocOutput.h:37
TDocParser::fLastClassDoc
TString fLastClassDoc
Definition: TDocParser.h:95
TDocParser::ProcessComment
virtual Bool_t ProcessComment()
Parse the current line as a comment, handling directives and re-formatting the comment: remove "/*",...
Definition: TDocParser.cxx:1928
Ssiz_t
int Ssiz_t
Definition: RtypesCore.h:67
TDocParser::kDocFunc
@ kDocFunc
Definition: TDocParser.h:48
TDocParser::fLineNo
UInt_t fLineNo
Definition: TDocParser.h:88
TDocParser::kParseContextFlagMask
@ kParseContextFlagMask
Definition: TDocParser.h:81
TDocParser::ExpandCPPLine
virtual void ExpandCPPLine(TString &line, Ssiz_t &pos)
Expand preprocessor statements.
Definition: TDocParser.cxx:911
TDocParser::WriteSourceLine
void WriteSourceLine(std::ostream &out)
Write fLineSource to out.
Definition: TDocParser.cxx:2307
TDocParser::InContext
UInt_t InContext(Int_t context) const
checks whether we are in a parse context, return the entry closest to the current context.
Definition: TDocParser.cxx:1158
TObject.h
TClass
TClass instances represent classes, structs and namespaces in the ROOT type system.
Definition: TClass.h:80
file
Definition: file.py:1
UChar_t
unsigned char UChar_t
Definition: RtypesCore.h:38
TObject
Mother of all ROOT objects.
Definition: TObject.h:37
ClassDef
#define ClassDef(name, id)
Definition: Rtypes.h:325
TClassDocOutput
Definition: TClassDocOutput.h:21
TDocParser::kDocClass
@ kDocClass
Definition: TDocParser.h:49
TDocParser::WriteClassDoc
void WriteClassDoc(std::ostream &out, Bool_t first=kTRUE)
Write the class description depending (among others) on fClassDocState.
Definition: TDocParser.cxx:2096
TDocParser::fMethods
THashList fMethods[3]
Definition: TDocParser.h:122
TDocParser::fSourceInfoTags
TString fSourceInfoTags[kNumSourceInfos]
Definition: TDocParser.h:117
name
char name[80]
Definition: TGX11.cxx:110
TDocParser::fComment
TString fComment
Definition: TDocParser.h:93
TDocParser::AddClassDataMembersRecursively
void AddClassDataMembersRecursively(TBaseClass *bc)
Add data members of fCurrentClass and of bc to datamembers, recursively.
Definition: TDocParser.cxx:306
TDocParser::fClassDescrTag
TString fClassDescrTag
Definition: TDocParser.h:116
TDocParser::GetMethods
const TList * GetMethods(EAccess access) const
Definition: TDocParser.h:170
TDocParser::GetLineNumber
Long_t GetLineNumber() const
Definition: TDocParser.h:174
TDocMethodWrapper::kDocumented
@ kDocumented
Definition: TDocParser.h:41
TDocParser::GetEnums
const TList * GetEnums(EAccess access) const
Definition: TDocParser.h:176
TDocParser::~TDocParser
virtual ~TDocParser()
destructor, checking whether all methods have been found for gDebug > 3
Definition: TDocParser.cxx:211
TDocParser::EDocContext
EDocContext
Definition: TDocParser.h:46
TDocParser::Convert
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".
Definition: TDocParser.cxx:402
TDocParser::fCheckForMethod
Bool_t fCheckForMethod
Definition: TDocParser.h:106
TDocParser::kClassDoc_Uninitialized
@ kClassDoc_Uninitialized
Definition: TDocParser.h:108
TDocParser::fDirectiveHandlers
TList fDirectiveHandlers
Definition: TDocParser.h:118
type
int type
Definition: TGX11.cxx:121
TDocParser::EAccess
EAccess
Definition: TDocParser.h:62
TDocParser::fDocOutput
TDocOutput * fDocOutput
Definition: TDocParser.h:87
TDocParser::fCurrentMethodTag
TString fCurrentMethodTag
Definition: TDocParser.h:99
TDocParser::Parse
virtual void Parse(std::ostream &out)
Locate methods, starting in the source file, then inline, then immediately inside the class declarati...
Definition: TDocParser.cxx:1573
TDocParser::GetSourceInfo
const char * GetSourceInfo(ESourceInfo type) const
Definition: TDocParser.h:177
TDocParser::IsDirective
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...
Definition: TDocParser.cxx:1253
TDocParser::IsWord
static Bool_t IsWord(UChar_t c)
Check if c is a valid first character for C++ name.
Definition: TDocParser.cxx:1324
TDocParser::kInfoLastUpdate
@ kInfoLastUpdate
Definition: TDocParser.h:55
TDocParser::kParseContextMask
@ kParseContextMask
Definition: TDocParser.h:77
TDocParser::fDataMembers
TList fDataMembers[6]
Definition: TDocParser.h:123
TList
A doubly linked list.
Definition: TList.h:44
TDocParser::kClassDoc_LookingNothingFound
@ kClassDoc_LookingNothingFound
Definition: TDocParser.h:109
int
TDocParser::kNumParseContexts
@ kNumParseContexts
Definition: TDocParser.h:76