include/root/TDocParser.h

0001 // @(#)root/html:$Id$
0002 // Author: Axel Naumann 2007-01-09
0003
0004 /*************************************************************************
0005  * Copyright (C) 1995-2007, Rene Brun and Fons Rademakers.               *
0006  * All rights reserved.                                                  *
0007  *                                                                       *
0008  * For the licensing terms see $ROOTSYS/LICENSE.                         *
0009  * For the list of contributors see $ROOTSYS/README/CREDITS.             *
0010  *************************************************************************/
0011
0012 #ifndef ROOT_TDocParser
0013 #define ROOT_TDocParser
0014
0015 ////////////////////////////////////////////////////////////////////////////
0016 //                                                                        //
0017 // TDocParser                                                             //
0018 //                                                                        //
0019 // Parses documentation in source files                                   //
0020 //                                                                        //
0021 ////////////////////////////////////////////////////////////////////////////
0022
0023 #include <list>
0024 #include <set>
0025 #include <map>
0026
0027 #include "TObject.h"
0028 #include "THashList.h"
0029 #include "TString.h"
0030
0031 class TBaseClass;
0032 class TClass;
0033 class TClassDocOutput;
0034 class TDocOutput;
0035 class THtml;
0036
0037 class TDocMethodWrapper: public TObject {
0038 public:
0039    virtual TMethod* GetMethod() const = 0;
0040    virtual Int_t GetOverloadIdx() const = 0;
0041    enum { kDocumented = 14 };
0042 };
0043
0044 class TDocParser: public TObject {
0045 protected:
0046    enum EDocContext {
0047       kIgnore,
0048       kDocFunc,
0049       kDocClass,
0050       kNumDocContexts
0051    };
0052
0053 public:
0054    enum ESourceInfo {
0055       kInfoLastUpdate,
0056       kInfoAuthor,
0057       kInfoCopyright,
0058       kInfoLastChanged,
0059       kInfoLastGenerated,
0060       kNumSourceInfos
0061    };
0062    enum EAccess {
0063       kPrivate,
0064       kProtected,
0065       kPublic
0066    };
0067    enum EParseContext {
0068       kNoContext,
0069       kCode,
0070       kComment,
0071       kDirective,
0072       kString,
0073       kKeyword,
0074       kCPP,
0075       kVerbatim,
0076       kNumParseContexts,
0077       kParseContextMask = BIT(4) - 1
0078    };
0079    enum EParseContextFlag {
0080       kCXXComment = BIT(4), // kComment is a C++ comment, or macro/html/latex content is surrounded by /* */
0081       kParseContextFlagMask = (UInt_t)(~(BIT(4) - 1))
0082
0083    };
0084
0085 protected:
0086    THtml*         fHtml;            // THtml object using us
0087    TDocOutput*    fDocOutput;       // TDocOutput invoking us
0088    UInt_t         fLineNo;          // current line number
0089    TString        fLineRaw;         // current line
0090    TString        fLineStripped;    // current line without surrounding spaces
0091    TString        fLineComment;         // current line with links and directives for doc
0092    TString        fLineSource;      // current line with links
0093    TString        fComment;         // current comment
0094    TString        fFirstClassDoc;   // first class-doc found - per file, taken if fLastClassDoc is empty
0095    TString        fLastClassDoc;    // last class-doc found - becomes class doc at ClassImp or first method
0096    TClass*        fCurrentClass;    // current class context of sources being parsed
0097    TClass*        fRecentClass;     // recently seen class context of sources being parsed, e.g. for Convert()
0098    TString        fCurrentModule;   // current module context of sources being parsed
0099    TString        fCurrentMethodTag;// name_idx of the currently parsed method
0100    Int_t          fDirectiveCount;  // index of directive for current method
0101    Long_t         fLineNumber;      // source line number
0102    TString        fCurrentFile;     // current source / header file name
0103    std::map<std::string /*name*/, Int_t > fMethodCounts;     // number of undocumented overloads
0104    EDocContext    fDocContext;      // current context of parsed sources for documenting
0105    std::list<UInt_t> fParseContext; // current context of parsed sources
0106    Bool_t         fCheckForMethod;  // whether to check the current line for a method
0107    enum {
0108       kClassDoc_Uninitialized,
0109       kClassDoc_LookingNothingFound,
0110       kClassDoc_LookingHaveSomething,
0111       kClassDoc_Written,
0112       kClassDoc_Ignore,
0113       kClassDoc_NumStates
0114    }              fClassDocState; // whether we found the class description
0115    Bool_t         fCommentAtBOL;    // at the beginning of the current line, fParseContext contained kComment
0116    TString        fClassDescrTag;   // tag for finding the class description
0117    TString        fSourceInfoTags[kNumSourceInfos]; // tags for source info elements (copyright, last changed, author)
0118    TList          fDirectiveHandlers;// handler for doc directives (TDocDirective objects)
0119    Bool_t         fAllowDirectives;  // whether directives are to be interpreted
0120    std::set<UInt_t> fExtraLinesWithAnchor; // lines that need an additional anchor
0121    TString        fSourceInfo[kNumSourceInfos];// author, last changed, ...
0122    THashList      fMethods[3];      // methods as TMethodWrapper objects (by access)
0123    TList          fDataMembers[6];  // data members (by access, plus enums)
0124
0125    static std::set<std::string>  fgKeywords; // C++ keywords
0126
0127    void           AddClassMethodsRecursively(TBaseClass* bc);
0128    void           AddClassDataMembersRecursively(TBaseClass* bc);
0129    EParseContext  Context() const { return fParseContext.empty() ? kComment : (EParseContext)(fParseContext.back() & kParseContextMask); }
0130    virtual void   ExpandCPPLine(TString& line, Ssiz_t& pos);
0131    virtual Bool_t HandleDirective(TString& keyword, Ssiz_t& pos,
0132       TString& word, Ssiz_t& copiedToCommentUpTo);
0133    void           InitKeywords() const;
0134    virtual TClass* IsDirective(const TString& line, Ssiz_t pos, const TString& word, Bool_t& begin) const;
0135    TMethod*       LocateMethodInCurrentLine(Ssiz_t& posMethodName, TString& ret,
0136       TString& name, TString& params, Bool_t& isconst,
0137       std::ostream &srcOut, TString &anchor,
0138       std::ifstream& sourcefile, Bool_t allowPureVirtual);
0139    void           LocateMethodsInSource(std::ostream& out);
0140    void           LocateMethodsInHeaderInline(std::ostream& out);
0141    void           LocateMethodsInHeaderClassDecl(std::ostream& out);
0142    void           LocateMethods(std::ostream& out, const char* filename,
0143                                 Bool_t lookForSourceInfo = kTRUE,
0144                                 Bool_t useDocxxStyle = kFALSE,
0145                                 Bool_t allowPureVirtual = kFALSE,
0146                                 const char* methodPattern = 0,
0147                                 const char* sourceExt = 0);
0148    virtual Bool_t ProcessComment();
0149    void           RemoveCommentContext(Bool_t cxxcomment);
0150    void           WriteClassDoc(std::ostream& out, Bool_t first = kTRUE);
0151    void           WriteMethod(std::ostream& out, TString& ret,
0152                               TString& name, TString& params,
0153                               Bool_t isconst,
0154                               const char* file, TString& anchor,
0155                               TString& codeOneLiner);
0156    void           WriteSourceLine(std::ostream& out);
0157
0158 public:
0159    TDocParser(TClassDocOutput& docOutput, TClass* cl);
0160    TDocParser(TDocOutput& docOutput);
0161          ~TDocParser() override;
0162
0163    static void   AnchorFromLine(const TString& line, TString& anchor);
0164    void          Convert(std::ostream& out, std::istream& in, const char* relpath,
0165                          Bool_t isCode, Bool_t interpretDirectives);
0166    void          DecrementMethodCount(const char* name);
0167    virtual void  DecorateKeywords(std::ostream& out, const char* text);
0168    virtual void  DecorateKeywords(TString& text);
0169    virtual void  DeleteDirectiveOutput() const;
0170    const TList*  GetMethods(EAccess access) const { return &fMethods[access]; }
0171    TClass*       GetCurrentClass() const { return fCurrentClass; }
0172    void          GetCurrentModule(TString& out_module) const;
0173    TDocOutput*   GetDocOutput() const { return fDocOutput; }
0174    Long_t        GetLineNumber() const { return fLineNumber; }
0175    const TList*  GetDataMembers(EAccess access) const { return &fDataMembers[access]; }
0176    const TList*  GetEnums(EAccess access) const { return &fDataMembers[access+3]; }
0177    const char*   GetSourceInfo(ESourceInfo type) const { return fSourceInfo[type]; }
0178    void          SetCurrentModule(const char* module) { fCurrentModule = module; }
0179
0180    UInt_t        InContext(Int_t context) const;
0181    static Bool_t IsName(UChar_t c);
0182    static Bool_t IsWord(UChar_t c);
0183
0184    virtual void  Parse(std::ostream& out);
0185    static Bool_t Strip(TString& s);
0186
0187    ClassDefOverride(TDocParser,0); // parser for reference documentation
0188 };
0189
0190 #endif // ROOT_TDocParser