doxygen.cpp

doxygen(一个自动从源代码生成文档的工具)的源代码

      {
        text+="matches the following input files:\n";
        text+=showFileDefMatches(Doxygen::inputNameDict,root->includeFile);
        text+="Please use a more specific name by "
            "including a (larger) part of the path!";
      }
      else // name is not an input file
      {
        text+="is not an input file";
      }
      warn(root->fileName,root->startLine,text);
    }
    else if (root->includeFile.isEmpty() && ifd &&
        // see if the file extension makes sense
        guessSection(ifd->name())==Entry::HEADER_SEC)
    { // implicit assumption
      fd=ifd;
    }

    // if a file is found, we mark it as a source file.
    if (fd)
    {
      QCString iName = !root->includeName.isEmpty() ? 
                       root->includeName.data() : root->includeFile.data();
      bool local=FALSE;
      if (!iName.isEmpty()) // user specified include file
      {
        local = iName.at(0)=='"'; // is it a local include file
        if (local || iName.at(0)=='<')
        {
          iName=iName.mid(1,iName.length()-2); // strip quotes or brackets
        }
      }
      else // use name of the file containing the class definition
      {
        iName=fd->name();
      }
      if (fd->generateSourceFile()) // generate code for header
      {
        cd->setIncludeFile(fd,iName,local);
      }
      else // put #include in the class documentation without link
      {
        cd->setIncludeFile(0,iName,local);
      }
    }
  }
}

static bool addNamespace(Entry *root,ClassDef *cd)
{
  // see if this class is defined inside a namespace
  if (root->section & Entry::COMPOUND_MASK)
  {
    Entry *e = root->parent;
    while (e)
    {
      if (e->section==Entry::NAMESPACE_SEC)
      {
        NamespaceDef *nd=0;
        //printf("addNameSpace() trying: %s\n",e->name.data());
        QCString nsName = stripAnonymousNamespaceScope(e->name);
        if (!nsName.isEmpty() && nsName.at(0)!='@' &&
            (nd=getResolvedNamespace(nsName))
           )
        {
          cd->setNamespace(nd);
          nd->insertClass(cd);
          return TRUE;
        }
      }
      e=e->parent;
    } 
  }
  return FALSE;
}

static Definition *findScope(Entry *root,int level=0)
{
  if (root==0) return 0;
  //printf("start findScope name=%s\n",root->name.data());
  Definition *result=0;
  if (root->section&Entry::SCOPE_MASK)
  {
    result = findScope(root->parent,level+1); // traverse to the root of the tree
    if (result)
    {
      //printf("Found %s inside %s at level %d\n",root->name.data(),result->name().data(),level);
      // TODO: look at template arguments
      result = result->findInnerCompound(root->name);
    }
    else // reached the global scope
    {
      // TODO: look at template arguments
      result = Doxygen::globalScope->findInnerCompound(root->name);
      //printf("Found in globalScope %s at level %d\n",result->name().data(),level);
    }
  }
  //printf("end findScope(%s,%d)=%s\n",root->name.data(),
  //       level,result==0 ? "<none>" : result->name().data());
  return result;
}

static Definition *findScopeFromQualifiedName(Definition *startScope,const QCString &n)
{
  //printf("findScopeFromQualifiedName(%s,%s)\n",startScope ? startScope->name().data() : 0, n.data());
  Definition *resultScope=startScope;
  if (resultScope==0) resultScope=Doxygen::globalScope;
  QCString scope=stripTemplateSpecifiersFromScope(n,FALSE);
  int l1=0,i1;
  i1=getScopeFragment(scope,0,&l1);
  if (i1==-1) return resultScope;
  int p=i1+l1,l2=0,i2;
  while ((i2=getScopeFragment(scope,p,&l2))!=-1)
  {
    QCString nestedNameSpecifier = scope.mid(i1,l1);
    //Definition *oldScope = resultScope;
    resultScope = resultScope->findInnerCompound(nestedNameSpecifier);
    if (resultScope==0) 
    {
      //printf("name %s not found in scope %s\n",nestedNameSpecifier.data(),oldScope->name().data());
      return 0;
    }
    i1=i2;
    l1=l2;
    p=i2+l2;
  }
  //printf("scope %s\n",resultScope->name().data());
  return resultScope;
}

ArgumentList *getTemplateArgumentsFromName(
                  const QCString &name,
                  const QList<ArgumentList> *tArgLists)
{
  if (tArgLists==0) return 0;
  
  QListIterator<ArgumentList> ali(*tArgLists);
  // for each scope fragment, check if it is a template and advance through
  // the list if so.
  int i,p=0;
  while ((i=name.find("::",p))!=-1)
  {
    NamespaceDef *nd = Doxygen::namespaceSDict[name.left(i)];
    if (nd==0)
    {
      ClassDef *cd = getClass(name.left(i));
      if (cd)
      {
        if (cd->templateArguments())
        {
          ++ali;
        }
      }
    }
    p=i+2;
  }
  return ali.current();
}

            
//----------------------------------------------------------------------
// build a list of all classes mentioned in the documentation
// and all classes that have a documentation block before their definition.
static void buildClassList(Entry *root)
{
  if (
       ((root->section & Entry::COMPOUNDDOC_MASK) ||
        ((root->section & Entry::COMPOUND_MASK))
       ) && 
       !root->name.isEmpty()
     )
  {
    QCString fullName=removeRedundantWhiteSpace(root->name);
    if (fullName.isEmpty())
    {
      // this should not be called
      warn(root->fileName,root->startLine,
           "Warning: invalid class name found!"
          );
    }
    else 
    {
      Debug::print(Debug::Classes,0,"  Found class with raw name %s\n",fullName.data());

      fullName=stripAnonymousNamespaceScope(fullName);
      fullName=stripTemplateSpecifiersFromScope(fullName);
        
      Debug::print(Debug::Classes,0,"  Found class with name %s\n",fullName.data());

      bool ambig;
      ClassDef *cd;
      //printf("findFileDef(%s)\n",root->fileName.data());
      FileDef *fd=findFileDef(Doxygen::inputNameDict,root->fileName,ambig);

      if ((cd=getClass(fullName))) 
      {
        Debug::print(Debug::Classes,0,"  Existing class!\n",fullName.data());
        //if (cd->templateArguments()==0)
        //{
        //  //printf("existing ClassDef tempArgList=%p specScope=%s\n",root->tArgList,root->scopeSpec.data());
        //  cd->setTemplateArguments(tArgList);
        //}
        if (!root->doc.isEmpty() || !root->brief.isEmpty() || 
            (root->bodyLine!=-1 && Config_getBool("SOURCE_BROWSER"))
           ) 
          // block contains something that ends up in the docs
        { 
          if (!root->doc.isEmpty() && !cd->documentation().isEmpty())
          {
            warn(
                 root->fileName,root->startLine,
                 "Warning: class %s already has a detailed description. "
                 "Skipping the one found here.",
                 fullName.data()
                );
          }
          else if (!root->doc.isEmpty())
          {
            cd->setDocumentation(root->doc);
          }
          if (!root->brief.isEmpty() && !cd->briefDescription().isEmpty())
          {
            warn(
                 root->fileName,root->startLine,
                 "Warning: class %s already has a brief description\n"
                 "         skipping the one found here.",
                 fullName.data()
                );
          }
          else if (!root->brief.isEmpty())
          {
            cd->setBriefDescription(root->brief);
          }
          if (root->bodyLine!=-1 && cd->getStartBodyLine()==-1)
          {
            cd->setBodySegment(root->bodyLine,root->endBodyLine);
            cd->setBodyDef(findFileDef(Doxygen::inputNameDict,root->fileName,ambig));
          }
          cd->addSectionsToDefinition(root->anchors);
          cd->setName(fullName); // change name to match docs
        }
        cd->setFileDef(fd);
        if (cd->hasDocumentation())
        {
          addIncludeFile(cd,fd,root);
        }
        addNamespace(root,cd);
        if (fd && (root->section & Entry::COMPOUND_MASK)) 
        {
          //printf(">> Inserting class `%s' in file `%s' (root->fileName=`%s')\n",
          //    cd->name().data(),
          //    fd->name().data(),
          //    root->fileName.data()
          //   );
          fd->insertClass(cd);
        }
        addClassToGroups(root,cd);
        cd->setRefItems(root->todoId,root->testId,root->bugId);
        if (!root->subGrouping) cd->setSubGrouping(FALSE);

        if (cd->templateArguments()==0) 
        {
          // this happens if a template class declared with @class is found
          // before the actual definition.
          ArgumentList *tArgList = 
            getTemplateArgumentsFromName(fullName,root->tArgLists);
          cd->setTemplateArguments(tArgList);
        }
      }
      else // new class
      {
        
        ClassDef::CompoundType sec=ClassDef::Class; 
        switch(root->section)
        {
          case Entry::UNION_SEC: 
          case Entry::UNIONDOC_SEC: 
            sec=ClassDef::Union; break;
          case Entry::STRUCT_SEC:
          case Entry::STRUCTDOC_SEC: 
            sec=ClassDef::Struct; break;
          case Entry::INTERFACE_SEC:
          case Entry::INTERFACEDOC_SEC:
            sec=ClassDef::Interface; break;
          case Entry::EXCEPTION_SEC:
          case Entry::EXCEPTIONDOC_SEC:
            sec=ClassDef::Exception; break;
        }
        Debug::print(Debug::Classes,0,"  New class `%s' (sec=0x%08x)! #tArgLists=%d\n",
            fullName.data(),root->section,root->tArgLists ? (int)root->tArgLists->count() : -1);
        QCString className;
        QCString namespaceName;
        extractNamespaceName(fullName,className,namespaceName);

        //printf("New class: namespace `%s' name=`%s'\n",className.data(),namespaceName.data());
        
        QCString tagName;
        QCString refFileName;
        if (root->tagInfo)
        {
          tagName     = root->tagInfo->tagName;
          refFileName = root->tagInfo->fileName;
        }
        ClassDef *cd=new ClassDef(root->fileName,root->startLine,fullName,sec,
                                  tagName,refFileName);
        cd->setDocumentation(root->doc); // copy docs to definition
        cd->setBriefDescription(root->brief);
        //printf("new ClassDef %s tempArgList=%p specScope=%s\n",fullName.data(),root->tArgList,root->scopeSpec.data());


        ArgumentList *tArgList = 
            getTemplateArgumentsFromName(fullName,root->tArgLists);
        //printf("class %s template args=%s\n",fullName.data(),
        //    tArgList ? tempArgListToString(tArgList).data() : "<none>");
        cd->setTemplateArguments(tArgList);
        cd->setProtection(root->protection);
        cd->addSectionsToDefinition(root->anchors);
        cd->setIsStatic(root->stat);

        // file definition containing the class cd
        cd->setBodySegment(root->bodyLine,root->endBodyLine);
        cd->setBodyDef(fd);
        if (!root->subGrouping) cd->setSubGrouping(FALSE);

        addClassToGroups(root,cd);
        cd->setRefItems(root->todoId,root->testId,root->bugId);

        // see if the class is found inside a namespace 
        bool found=addNamespace(root,cd);

        cd->setFileDef(fd);
        if (cd->hasDocumentation())
        {
          addIncludeFile(cd,fd,root);
        }
        
        // namespace is part of the class name
        if (!found && !namespaceName.isEmpty())
        {
          NamespaceDef *nd = getResolvedNamespace(namespaceName);
          if (nd)
          {
            cd->setNamespace(nd);
            nd->insertClass(cd);
            found=TRUE;
          }
        }
        
        // if the class is not in a namespace then we insert 
        // it in the file definition
        if (!found && fd && (root->section & Entry::COMPOUND_MASK)) 
        {
          //printf(">> Inserting class `%s' in file `%s' (root->fileName=`%s')\n",
          //    cd->name().data(),
          //    fd->name().data(),
          //    root->fileName.data()
          //   );
          fd->insertClass(cd);
        }
        
        // the empty string test is needed for extract all case
        cd->setBriefDescription(root->brief);
        cd->insertUsedFile(root->fileName);

        // add class to the list
        //printf("ClassDict.insert(%s)\n",resolveDefines(fullName).data());
        Doxygen::classSDict.append(fullName,cd);

        // also add class to the correct structural context 
        Definition *d = findScopeFromQualifiedName(Doxygen::globalScope,fullName);
        if (d==0)
        {
          //warn(root->fileName,root->startLine,
          //     "Warning: Internal inconsistency: scope for class %s not "
          //     "found!\n",fullName.data()
          //    );
        }
        else
        {
          //printf("****** adding %s to scope %s\n",cd->name().data(),d->name().data());
          d->addInnerCompound(cd);
          cd->setOuterScope(d);
        }
      }
    }
  }
  EntryListIterator eli(*root->sublist);
  Entry *e;
  for (;(e=eli.current());++eli)
  {
    buildClassList(e);
  }
}

//----------------------------------------------------------------------
// build a list of all namespaces mentioned in the documentation
// and all namespaces that have a documentation block before their definition.
static void buildNamespaceList(Entry *root)