Logo ROOT   6.30.04
Reference Guide
 All Namespaces Files Pages
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 {
47  kIgnore,
48  kDocFunc,
49  kDocClass,
50  kNumDocContexts
51  };
52 
53 public:
54  enum ESourceInfo {
55  kInfoLastUpdate,
56  kInfoAuthor,
57  kInfoCopyright,
58  kInfoLastChanged,
59  kInfoLastGenerated,
60  kNumSourceInfos
61  };
62  enum EAccess {
63  kPrivate,
64  kProtected,
65  kPublic
66  };
67  enum EParseContext {
68  kNoContext,
69  kCode,
70  kComment,
71  kDirective,
72  kString,
73  kKeyword,
74  kCPP,
75  kVerbatim,
76  kNumParseContexts,
77  kParseContextMask = BIT(4) - 1
78  };
79  enum EParseContextFlag {
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 {
108  kClassDoc_Uninitialized,
109  kClassDoc_LookingNothingFound,
110  kClassDoc_LookingHaveSomething,
111  kClassDoc_Written,
112  kClassDoc_Ignore,
113  kClassDoc_NumStates
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 
127  void AddClassMethodsRecursively(TBaseClass* bc);
128  void AddClassDataMembersRecursively(TBaseClass* bc);
129  EParseContext Context() const { return fParseContext.empty() ? kComment : (EParseContext)(fParseContext.back() & kParseContextMask); }
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