ROOT logo
// @(#)root/html:$Id: TDocParser.h 31111 2009-11-12 09:57:56Z axel $
// Author: Axel Naumann 2007-01-09

/*************************************************************************
 * Copyright (C) 1995-2007, Rene Brun and Fons Rademakers.               *
 * All rights reserved.                                                  *
 *                                                                       *
 * For the licensing terms see $ROOTSYS/LICENSE.                         *
 * For the list of contributors see $ROOTSYS/README/CREDITS.             *
 *************************************************************************/

#ifndef ROOT_TDocParser
#define ROOT_TDocParser

////////////////////////////////////////////////////////////////////////////
//                                                                        //
// TDocParser                                                             //
//                                                                        //
// Parses documentation in source files                                   //
//                                                                        //
////////////////////////////////////////////////////////////////////////////

#include <list>
#include <set>
#include <map>

#ifndef ROOT_TObject
#include "TObject.h"
#endif
#ifndef ROOT_THashList
#include "THashList.h"
#endif
#ifndef ROOT_TString
#include "TString.h"
#endif
#ifndef ROOT_Riosfwd
#include "Riosfwd.h"
#endif

class TBaseClass;
class TClass;
class TClassDocOutput;
class TDocOutput;
class THtml;

class TDocMethodWrapper: public TObject {
public:
   virtual TMethod* GetMethod() const = 0;
   virtual Int_t GetOverloadIdx() const = 0;
};

class TDocParser: public TObject {
protected:
   enum EDocContext {
      kIgnore,
      kDocFunc,
      kDocClass,
      kNumDocContexts
   };

public:
   enum ESourceInfo {
      kInfoLastUpdate,
      kInfoAuthor,
      kInfoCopyright,
      kInfoLastChanged,
      kInfoLastGenerated,
      kNumSourceInfos
   };
   enum EAccess {
      kPrivate,
      kProtected,
      kPublic
   };
   enum EParseContext {
      kNoContext,
      kCode,
      kComment,
      kDirective,
      kString,
      kKeyword,
      kCPP,
      kVerbatim,
      kNumParseContexts,
      kParseContextMask = BIT(4) - 1
   };
   enum EParseContextFlag {
      kCXXComment = BIT(4), // kComment is a C++ comment, or macro/html/latex content is surrounded by /* */
      kParseContextFlagMask = (UInt_t)(~(BIT(4) - 1))

   };

protected:
   THtml*         fHtml;            // THtml object using us
   TDocOutput*    fDocOutput;       // TDocOutput invoking us
   UInt_t         fLineNo;          // current line number
   TString        fLineRaw;         // current line
   TString        fLineStripped;    // current line without surrounding spaces
   TString        fLineComment;         // current line with links and directives for doc
   TString        fLineSource;      // current line with links
   TString        fComment;         // current comment
   TString        fFirstClassDoc;   // first class-doc found - per file, taken if fLastClassDoc is empty
   TString        fLastClassDoc;    // last class-doc found - becomes class doc at ClassImp or first method
   TClass*        fCurrentClass;    // current class context of sources being parsed
   TClass*        fRecentClass;     // recently seen class context of sources being parsed, e.g. for Convert()
   TString        fCurrentModule;   // current module context of sources being parsed
   TString        fCurrentMethodTag;// name_idx of the currently parsed method
   Int_t          fDirectiveCount;  // index of directive for current method
   Long_t         fLineNumber;      // source line number
   TString        fCurrentFile;     // current source / header file name
   std::map<std::string /*name*/, Int_t > fMethodCounts;     // number of undocumented overloads
   EDocContext    fDocContext;      // current context of parsed sources for documenting
   std::list<UInt_t> fParseContext; // current context of parsed sources
   Bool_t         fCheckForMethod;  // whether to check the current line for a method
   enum {
      kClassDoc_Uninitialized,
      kClassDoc_LookingNothingFound,
      kClassDoc_LookingHaveSomething,
      kClassDoc_Written,
      kClassDoc_Ignore,
      kClassDoc_NumStates
   }              fClassDocState; // whether we found the class description
   Bool_t         fCommentAtBOL;    // at the beginning of the current line, fParseContext contained kComment
   TString        fClassDescrTag;   // tag for finding the class description
   TString        fSourceInfoTags[kNumSourceInfos]; // tags for source info elements (copyright, last changed, author)
   TList          fDirectiveHandlers;// handler for doc directives (TDocDirective objects)
   Bool_t         fAllowDirectives;  // whether directives are to be interpreted
   std::set<UInt_t> fExtraLinesWithAnchor; // lines that need an additional anchor
   TString        fSourceInfo[kNumSourceInfos];// author, last changed, ...
   THashList      fMethods[3];      // methods as TMethodWrapper objects (by access)
   TList          fDataMembers[6];  // data members (by access, plus enums)

   static std::set<std::string>  fgKeywords; // C++ keywords

   void           AddClassMethodsRecursively(TBaseClass* bc);
   void           AddClassDataMembersRecursively(TBaseClass* bc);
   EParseContext  Context() const { return fParseContext.empty() ? kComment : (EParseContext)(fParseContext.back() & kParseContextMask); }
   virtual void   ExpandCPPLine(TString& line, Ssiz_t& pos);
   virtual Bool_t HandleDirective(TString& keyword, Ssiz_t& pos, 
      TString& word, Ssiz_t& copiedToCommentUpTo);
   virtual void   InitKeywords() const;
   virtual TClass* IsDirective(const TString& line, Ssiz_t pos, const TString& word, Bool_t& begin) const;
   TMethod*       LocateMethodInCurrentLine(Ssiz_t& posMethodName, TString& ret, 
      TString& name, TString& params, std::ostream &srcOut, TString &anchor, 
      std::ifstream& sourcefile, Bool_t allowPureVirtual);
   void           LocateMethodsInSource(std::ostream& out);
   void           LocateMethodsInHeaderInline(std::ostream& out);
   void           LocateMethodsInHeaderClassDecl(std::ostream& 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);
   virtual Bool_t ProcessComment();
   void           RemoveCommentContext(Bool_t cxxcomment);
   void           WriteClassDoc(std::ostream& out, Bool_t first = kTRUE);
   void           WriteMethod(std::ostream& out, TString& ret, 
                              TString& name, TString& params,
                              const char* file, TString& anchor,
                              TString& codeOneLiner);
   void           WriteSourceLine(std::ostream& out);

public:
   TDocParser(TClassDocOutput& docOutput, TClass* cl);
   TDocParser(TDocOutput& docOutput);
   virtual       ~TDocParser();

   static void   AnchorFromLine(const TString& line, TString& anchor);
   void          Convert(std::ostream& out, std::istream& in, const char* relpath,
                         Bool_t isCode, Bool_t interpretDirectives);
   void          DecrementMethodCount(const char* name);
   virtual void  DecorateKeywords(std::ostream& out, const char* text);
   virtual void  DecorateKeywords(TString& text);
   virtual void  DeleteDirectiveOutput() const;
   const TList*  GetMethods(EAccess access) const { return &fMethods[access]; }
   TClass*       GetCurrentClass() const { return fCurrentClass; }
   void          GetCurrentModule(TString& out_module) const;
   TDocOutput*   GetDocOutput() const { return fDocOutput; }
   Long_t        GetLineNumber() const { return fLineNumber; }
   const TList*  GetDataMembers(EAccess access) const { return &fDataMembers[access]; }
   const TList*  GetEnums(EAccess access) const { return &fDataMembers[access+3]; }
   const char*   GetSourceInfo(ESourceInfo type) const { return fSourceInfo[type]; }
   void          SetCurrentModule(const char* module) { fCurrentModule = module; }

   UInt_t        InContext(Int_t context) const;
   static Bool_t IsName(UChar_t c);
   static Bool_t IsWord(UChar_t c);

   virtual void  Parse(std::ostream& out);
   static Bool_t Strip(TString& s);

   ClassDef(TDocParser,0); // parser for reference documentation
};

#endif // ROOT_TDocParser
 TDocParser.h:1
 TDocParser.h:2
 TDocParser.h:3
 TDocParser.h:4
 TDocParser.h:5
 TDocParser.h:6
 TDocParser.h:7
 TDocParser.h:8
 TDocParser.h:9
 TDocParser.h:10
 TDocParser.h:11
 TDocParser.h:12
 TDocParser.h:13
 TDocParser.h:14
 TDocParser.h:15
 TDocParser.h:16
 TDocParser.h:17
 TDocParser.h:18
 TDocParser.h:19
 TDocParser.h:20
 TDocParser.h:21
 TDocParser.h:22
 TDocParser.h:23
 TDocParser.h:24
 TDocParser.h:25
 TDocParser.h:26
 TDocParser.h:27
 TDocParser.h:28
 TDocParser.h:29
 TDocParser.h:30
 TDocParser.h:31
 TDocParser.h:32
 TDocParser.h:33
 TDocParser.h:34
 TDocParser.h:35
 TDocParser.h:36
 TDocParser.h:37
 TDocParser.h:38
 TDocParser.h:39
 TDocParser.h:40
 TDocParser.h:41
 TDocParser.h:42
 TDocParser.h:43
 TDocParser.h:44
 TDocParser.h:45
 TDocParser.h:46
 TDocParser.h:47
 TDocParser.h:48
 TDocParser.h:49
 TDocParser.h:50
 TDocParser.h:51
 TDocParser.h:52
 TDocParser.h:53
 TDocParser.h:54
 TDocParser.h:55
 TDocParser.h:56
 TDocParser.h:57
 TDocParser.h:58
 TDocParser.h:59
 TDocParser.h:60
 TDocParser.h:61
 TDocParser.h:62
 TDocParser.h:63
 TDocParser.h:64
 TDocParser.h:65
 TDocParser.h:66
 TDocParser.h:67
 TDocParser.h:68
 TDocParser.h:69
 TDocParser.h:70
 TDocParser.h:71
 TDocParser.h:72
 TDocParser.h:73
 TDocParser.h:74
 TDocParser.h:75
 TDocParser.h:76
 TDocParser.h:77
 TDocParser.h:78
 TDocParser.h:79
 TDocParser.h:80
 TDocParser.h:81
 TDocParser.h:82
 TDocParser.h:83
 TDocParser.h:84
 TDocParser.h:85
 TDocParser.h:86
 TDocParser.h:87
 TDocParser.h:88
 TDocParser.h:89
 TDocParser.h:90
 TDocParser.h:91
 TDocParser.h:92
 TDocParser.h:93
 TDocParser.h:94
 TDocParser.h:95
 TDocParser.h:96
 TDocParser.h:97
 TDocParser.h:98
 TDocParser.h:99
 TDocParser.h:100
 TDocParser.h:101
 TDocParser.h:102
 TDocParser.h:103
 TDocParser.h:104
 TDocParser.h:105
 TDocParser.h:106
 TDocParser.h:107
 TDocParser.h:108
 TDocParser.h:109
 TDocParser.h:110
 TDocParser.h:111
 TDocParser.h:112
 TDocParser.h:113
 TDocParser.h:114
 TDocParser.h:115
 TDocParser.h:116
 TDocParser.h:117
 TDocParser.h:118
 TDocParser.h:119
 TDocParser.h:120
 TDocParser.h:121
 TDocParser.h:122
 TDocParser.h:123
 TDocParser.h:124
 TDocParser.h:125
 TDocParser.h:126
 TDocParser.h:127
 TDocParser.h:128
 TDocParser.h:129
 TDocParser.h:130
 TDocParser.h:131
 TDocParser.h:132
 TDocParser.h:133
 TDocParser.h:134
 TDocParser.h:135
 TDocParser.h:136
 TDocParser.h:137
 TDocParser.h:138
 TDocParser.h:139
 TDocParser.h:140
 TDocParser.h:141
 TDocParser.h:142
 TDocParser.h:143
 TDocParser.h:144
 TDocParser.h:145
 TDocParser.h:146
 TDocParser.h:147
 TDocParser.h:148
 TDocParser.h:149
 TDocParser.h:150
 TDocParser.h:151
 TDocParser.h:152
 TDocParser.h:153
 TDocParser.h:154
 TDocParser.h:155
 TDocParser.h:156
 TDocParser.h:157
 TDocParser.h:158
 TDocParser.h:159
 TDocParser.h:160
 TDocParser.h:161
 TDocParser.h:162
 TDocParser.h:163
 TDocParser.h:164
 TDocParser.h:165
 TDocParser.h:166
 TDocParser.h:167
 TDocParser.h:168
 TDocParser.h:169
 TDocParser.h:170
 TDocParser.h:171
 TDocParser.h:172
 TDocParser.h:173
 TDocParser.h:174
 TDocParser.h:175
 TDocParser.h:176
 TDocParser.h:177
 TDocParser.h:178
 TDocParser.h:179
 TDocParser.h:180
 TDocParser.h:181
 TDocParser.h:182
 TDocParser.h:183
 TDocParser.h:184
 TDocParser.h:185
 TDocParser.h:186
 TDocParser.h:187
 TDocParser.h:188
 TDocParser.h:189
 TDocParser.h:190
 TDocParser.h:191
 TDocParser.h:192
 TDocParser.h:193
 TDocParser.h:194
 TDocParser.h:195
 TDocParser.h:196