src/vhdldocgen.h

   1 /******************************************************************************
   2  *
   3  * Copyright (C) 1997-2012 by Dimitri van Heesch.
   4  *
   5  * Permission to use, copy, modify, and distribute this software and its
   6  * documentation under the terms of the GNU General Public License is hereby
   7  * granted. No representations are made about the suitability of this software
   8  * for any purpose. It is provided "as is" without express or implied warranty.
   9  * See the GNU General Public License for more details.
  10  *
  11  * Documents produced by Doxygen are derivative works derived from the
  12  * input used in their production; they are not affected by this license.
  13  *
  14  */
  15
  16 #ifndef VHDLDOCGEN_H
  17 #define VHDLDOCGEN_H
  18
  19 /**
  20  * This class implements functions for parsing and generating
  21  * vhdl documents
  22  */
  23
  24 #include <qdict.h>
  25 #include <qcstring.h>
  26 #include "layout.h"
  27 #include "memberlist.h"
  28
  29 class Entry;
  30 class ClassDef;
  31 class MemberDef;
  32 struct Argument;
  33
  34 /** Class for generating documentation specific for VHDL */
  35 class VhdlDocGen
  36 {
  37   public:
  38
  39     enum VhdlClasses       // Overlays: Protection
  40     {
  41       ENTITYCLASS,         // Overlays: Public
  42       PACKBODYCLASS,       // Overlays: Protected
  43       ARCHITECTURECLASS,   // Overlays: Private
  44       PACKAGECLASS         // Overlays: Package
  45     };
  46
  47     enum VhdlKeyWords
  48     {
  49       LIBRARY=1,
  50       ENTITY,
  51       PACKAGE_BODY,
  52       ARCHITECTURE,
  53       PACKAGE,
  54       ATTRIBUTE,
  55       SIGNAL,
  56       COMPONENT,
  57       CONSTANT,
  58       TYPE,
  59       SUBTYPE,
  60       FUNCTION,
  61       RECORD,
  62       PROCEDURE,
  63       USE,
  64       PROCESS,
  65       PORT,
  66       UNITS,
  67       GENERIC,
  68       INSTANTIATION,
  69       GROUP,
  70       VFILE,
  71       SHAREDVARIABLE,
  72       CONFIG,
  73       ALIAS,
  74       MISCELLANEOUS,
  75       UCF_CONST
  76     };
  77
  78     VhdlDocGen();
  79     virtual ~VhdlDocGen();
  80     static void init();
  81     static QCString convertFileNameToClassName(QCString name);
  82     // --- used by vhdlscanner.l -----------
  83
  84     static bool isSubClass(ClassDef* cd,ClassDef *scd, bool followInstances,int level);
  85
  86     static QCString getIndexWord(const char* ,int index);
  87     static  bool    foundInsertedComponent(const QCString& name,Entry* root);
  88     static bool     deleteCharRev(QCString &s,char c);
  89     static void     deleteAllChars(QCString &s,char c);
  90     static void     parseFuncProto(const char* text,
  91                                    QList<Argument>& ,
  92                                    QCString& name,
  93                                    QCString& ret,
  94                                    bool doc=false);
  95     // -----------------------------------
  96
  97     static void computeVhdlComponentRelations();
  98
  99     static QCString* findKeyWord(const QCString& word);
 100
 101     static ClassDef* getPackageName(const QCString& name);
 102     static MemberDef* findMember(const QCString& className,
 103                                  const QCString& memName);
 104     static void findAllPackages(const QCString& className,
 105                                 QDict<QCString>&);
 106     static MemberDef* findMemberDef(ClassDef* cd,
 107                                 const QCString& key,
 108                                 MemberList::ListType type);
 109     static ClassDef *getClass(const char *name);
 110     static MemberDef* findFunction(const QList<Argument> &ql,
 111                                    const QCString& name,
 112                                    const QCString& package, bool type);
 113     static bool compareString(const QCString& s1,
 114                               const QCString& s2);
 115     static QCString getClassTitle(const ClassDef*);
 116     static void writeInlineClassLink(const ClassDef*,
 117                                      OutputList &ol);
 118
 119     static bool isConstraint(const MemberDef *mdef)
 120     { return mdef->getMemberSpecifiers()==VhdlDocGen::UCF_CONST; }
 121     static bool isConfig(const MemberDef *mdef)
 122     { return mdef->getMemberSpecifiers()==VhdlDocGen::CONFIG; }
 123     static bool isAlias(const MemberDef *mdef)
 124     { return mdef->getMemberSpecifiers()==VhdlDocGen::ALIAS; }
 125     static bool isLibrary(const MemberDef *mdef)
 126     { return mdef->getMemberSpecifiers()==VhdlDocGen::LIBRARY; }
 127     static bool isGeneric(const MemberDef *mdef)
 128     { return mdef->getMemberSpecifiers()==VhdlDocGen::GENERIC; }
 129     static bool isPort(const MemberDef *mdef)
 130     { return mdef->getMemberSpecifiers()==VhdlDocGen::PORT; }
 131     static bool isComponent(const MemberDef *mdef)
 132     { return mdef->getMemberSpecifiers()==VhdlDocGen::COMPONENT; }
 133     static bool isPackage(const MemberDef *mdef)
 134     { return mdef->getMemberSpecifiers()==VhdlDocGen::USE; }
 135     static bool isEntity(const MemberDef *mdef)
 136     { return mdef->getMemberSpecifiers()==VhdlDocGen::ENTITY; }
 137     static bool isConstant(const MemberDef *mdef)
 138     { return mdef->getMemberSpecifiers()==VhdlDocGen::CONSTANT; }
 139     static bool isVType(const MemberDef *mdef)
 140     { return mdef->getMemberSpecifiers()==VhdlDocGen::TYPE; }
 141     static bool isSubType(const MemberDef *mdef)
 142     { return mdef->getMemberSpecifiers()==VhdlDocGen::SUBTYPE; }
 143     static bool isVhdlFunction(const MemberDef *mdef)
 144     { return mdef->getMemberSpecifiers()==VhdlDocGen::FUNCTION; }
 145     static bool isProcess(const MemberDef *mdef)
 146     { return mdef->getMemberSpecifiers()==VhdlDocGen::PROCESS; }
 147     static bool isSignal(const MemberDef *mdef)
 148     { return mdef->getMemberSpecifiers()==VhdlDocGen::SIGNAL; }
 149     static bool isAttribute(const MemberDef *mdef)
 150     { return mdef->getMemberSpecifiers()==VhdlDocGen::ATTRIBUTE; }
 151     static bool isSignals(const MemberDef *mdef)
 152     { return mdef->getMemberSpecifiers()==VhdlDocGen::SIGNAL; }
 153     static bool isProcedure(const MemberDef *mdef)
 154     { return mdef->getMemberSpecifiers()==VhdlDocGen::PROCEDURE; }
 155     static bool isRecord(const MemberDef *mdef)
 156     { return mdef->getMemberSpecifiers()==VhdlDocGen::RECORD; }
 157     static bool isArchitecture(const MemberDef *mdef)
 158     { return mdef->getMemberSpecifiers()==VhdlDocGen::ARCHITECTURE; }
 159     static bool isUnit(const MemberDef *mdef)
 160     { return mdef->getMemberSpecifiers()==VhdlDocGen::UNITS; }
 161     static bool isPackageBody(const MemberDef *mdef)
 162     { return mdef->getMemberSpecifiers()==VhdlDocGen::PACKAGE_BODY; }
 163     static bool isVariable(const MemberDef *mdef)
 164     { return mdef->getMemberSpecifiers()==VhdlDocGen::SHAREDVARIABLE; }
 165     static bool isFile(const MemberDef *mdef)
 166     { return mdef->getMemberSpecifiers()==VhdlDocGen::VFILE; }
 167     static bool isGroup(const MemberDef *mdef)
 168     { return mdef->getMemberSpecifiers()==VhdlDocGen::GROUP; }
 169     static bool isCompInst(const MemberDef *mdef)
 170     { return mdef->getMemberSpecifiers()==VhdlDocGen::INSTANTIATION; }
 171     static bool isMisc(const MemberDef *mdef)
 172     { return mdef->getMemberSpecifiers()==VhdlDocGen::MISCELLANEOUS; }
 173
 174     //-----------------------------------------------------
 175     // translatable items
 176
 177     static QCString trTypeString(int type);
 178     static QCString trVhdlType(int type,bool sing=true);
 179
 180     // trClassHierarchy.
 181     static QCString trDesignUnitHierarchy();
 182
 183     // trCompoundList
 184     static QCString trDesignUnitList();
 185
 186     // trCompoundMembers.
 187     static QCString trDesignUnitMembers();
 188
 189     // trCompoundListDescription
 190     static QCString trDesignUnitListDescription();
 191
 192     // trCompounds
 193     static QCString trDesignUnits();
 194
 195     // trCompoundIndex
 196     static QCString trDesignUnitIndex();
 197
 198     // trFunctions
 199     static QCString trFunctionAndProc();
 200
 201     //-----------------------------------------------------
 202
 203     static void prepareComment(QCString&);
 204     static void formatString(const QCString&,OutputList& ol,const MemberDef*);
 205
 206     static void writeFormatString(const QCString&,OutputList& ol,const MemberDef*);
 207     static void writeFunctionProto(OutputList& ol,const ArgumentList *al,const MemberDef*);
 208     static void writeProcessProto(OutputList& ol,const ArgumentList *al,const MemberDef*);
 209     static void writeProcedureProto(OutputList& ol, const ArgumentList *al,const MemberDef*);
 210     static void writeFuncProcDocu(const MemberDef *mdef, OutputList& ol,const ArgumentList* al,bool type=false);
 211     static void writeRecordProto(const MemberDef *mdef, OutputList& ol,const ArgumentList *al);
 212
 213     static void writeVHDLTypeDocumentation(const MemberDef* mdef, const Definition* d, OutputList &ol);
 214
 215     static void writeVhdlDeclarations(MemberList*,OutputList&,GroupDef*,ClassDef*,FileDef*,NamespaceDef*);
 216
 217     static void writeVHDLDeclaration(MemberDef* mdef,OutputList &ol,
 218         ClassDef *cd,NamespaceDef *nd,FileDef *fd,GroupDef *gd,
 219         bool inGroup);
 220
 221     static void writePlainVHDLDeclarations(MemberList* ml,OutputList &ol,
 222         ClassDef *cd,NamespaceDef *nd,FileDef *fd,GroupDef *gd,int specifier);
 223
 224     static void writeVHDLDeclarations(MemberList* ml,OutputList &ol,
 225         ClassDef *cd,NamespaceDef *nd,FileDef *fd,GroupDef *gd,
 226         const char *title,const char *subtitle,bool showEnumValues,int type);
 227
 228     static bool writeClassType(ClassDef *&,OutputList &ol ,QCString & cname);
 229
 230
 231     static QCString convertArgumentListToString(const ArgumentList* al,bool f);
 232     static QCString getProcessNumber();
 233     static QCString getRecordNumber();
 234
 235     static QCString getClassName(const ClassDef*);
 236     // obsolete
 237     // static void adjustRecordMember(MemberDef *mdef);
 238
 239     static void writeLink(const MemberDef* mdef,OutputList &ol);
 240     static void adjustMemberName(QCString& nn);
 241     static bool membersHaveSpecificType(MemberList *ml,int type);
 242     static void startFonts(const QCString& q, const char *keyword,OutputList& ol);
 243     static bool isNumber(const QCString& s);
 244     static QCString getProtectionName(int prot);
 245     static QCString splitString(QCString & str,  char c);
 246     static void parseUCF(const char*  input,Entry* entity,QCString f,bool vendor);
 247
 248     static bool findConstraintFile( LayoutNavEntry *lne);
 249
 250     static ClassDef*  findArchitecture(const ClassDef *cd);
 251     static ClassDef*  findArchitecture(QCString identifier, QCString entity_name);
 252
 253     static void writeCodeFragment( MemberDef *mdef,OutputList& ol);
 254     static void writeCodeFragment (OutputList& ol,int start, QCString & codeFragment,const MemberDef* mdef);
 255
 256     static void writeSource(MemberDef *mdef,OutputList& ol,QCString & cname);
 257     static void writeAlphbeticalClass(OutputList& ol,const ClassDef* cd,const QCString &);
 258
 259     static QCString  parseForConfig(QCString & entity,QCString & arch);
 260     static QCString  parseForBinding(QCString & entity,QCString & arch);
 261     static void addBaseClass(ClassDef* cd,ClassDef *ent);
 262
 263     static void writeOverview(OutputList &ol);
 264     static void writeOverview();
 265
 266   private:
 267     static void findAllArchitectures(QList<QCString>& ql,const ClassDef *cd);
 268     static bool compareArgList(ArgumentList*,ArgumentList*);
 269     static void writeVhdlLink(const ClassDef* cdd ,OutputList& ol,QCString& type,QCString& name,QCString& beh);
 270     static void writeStringLink(const MemberDef *mdef,QCString mem,OutputList& ol);
 271     static void writeRecUnitDocu( const MemberDef *md, OutputList& ol,QCString largs);
 272     static void  writeRecorUnit(QCString & largs,OutputList& ol ,const MemberDef *mdef);
 273 };
 274
 275 #endif