memberdef.cpp

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

  if (!briefDescription().isEmpty() && 
      Config_getBool("BRIEF_MEMBER_DESC") && 
      !annMemb)
  {
    ol.startMemberDescription();
    parseDoc(ol,m_defFileName,m_defLine,cname,name(),briefDescription());
    if (detailsVisible) 
    {
      ol.pushGeneratorState();
      ol.disableAllBut(OutputGenerator::Html);
      ol.endEmphasis();
      ol.docify(" ");
      if (group!=0 && gd==0) // forward link to the group
      {
        ol.startTextLink(group->getOutputFileBase(),anchor());
      }
      else
      {
        ol.startTextLink(0,anchor());
      }
      parseText(ol,theTranslator->trMore());
      ol.endTextLink();
      ol.startEmphasis();
      ol.popGeneratorState();
    }
    //ol.newParagraph();
    ol.endMemberDescription();
  }
  warnIfUndocumented();
}

bool MemberDef::isDetailedSectionLinkable() const          
{ 
  // the member has details documentation for any of the following reasons
  bool docFilter = 
         // treat everything as documented
         Config_getBool("EXTRACT_ALL") ||          
         // has detailed docs
         !documentation().isEmpty() ||             
         // is an enum with values that are documented
         (mtype==Enumeration && docEnumValues) ||  
         // is documented enum value
         (mtype==EnumValue && !briefDescription().isEmpty()) || 
         // has brief description that is part of the detailed description
         (!briefDescription().isEmpty() && 
          Config_getBool("ALWAYS_DETAILED_SEC") && 
          Config_getBool("REPEAT_BRIEF")
         ) ||
         // has a multi-line initialization block
         //(initLines>0 && initLines<maxInitLines) || 
         hasMultiLineInitializer() ||
         // has one or more documented arguments
         (argList!=0 && argList->hasDocumentation()); 
         
  // this is not a global static or global statics should be extracted
  bool staticFilter = getClassDef()!=0 || !isStatic() || Config_getBool("EXTRACT_STATIC"); 
         
  // only include members that are non-private unless EXTRACT_PRIVATE is
  // set to YES or the member is part of a group
  bool privateFilter = (protection()!=Private || 
                           Config_getBool("EXTRACT_PRIVATE") ||
                           mtype==Friend
                          );

  // member is part of an anonymous scope that is the type of
  // another member in the list.
  //
  bool inAnonymousScope = !briefDescription().isEmpty() && annUsed;

  return ((docFilter && staticFilter && privateFilter) || inAnonymousScope);
}

bool MemberDef::isDetailedSectionVisible(bool inGroup) const          
{ 
  bool groupFilter = getGroupDef()==0 || inGroup; 

  bool visible = isDetailedSectionLinkable() && groupFilter;
  //printf("MemberDef::isDetailedSectionVisible() %d\n",visible);
  return visible;
}

/*! Writes the "detailed documentation" section of this member to
 *  all active output formats.
 */
void MemberDef::writeDocumentation(MemberList *ml,OutputList &ol,
                                   const char *scName,
                                   Definition *container,
                                   bool inGroup
                                  )
{
  // if this member is in a group find the real scope name.
  bool hasDocs = isDetailedSectionVisible(inGroup);
  //printf("MemberDef::writeDocumentation(): name=`%s' hasDocs=`%d' containerType=%d inGroup=%d\n",
  //    name().data(),hasDocs,container->definitionType(),inGroup);
  if ( hasDocs )
  {
    QCString scopeName = scName;
    if (container->definitionType()==TypeGroup)
    {
      if (getClassDef())          scopeName=getClassDef()->name();
      else if (getNamespaceDef()) scopeName=getNamespaceDef()->name();
      else if (getFileDef())      scopeName=getFileDef()->name();
    }
  
    // get definition. 
    QCString cname  = container->name();
    QCString cfname = container->getOutputFileBase();  

    // get member name
    QCString doxyName=name().copy();
    // prepend scope if there is any. TODO: make this optional for C only docs
    if (scopeName) doxyName.prepend((QCString)scopeName+"::");

    QCString ldef = definition();
    if (isEnumerate()) 
    {
      if (name().at(0)=='@')
      {
        ldef = "anonymous enum";
      }
      else
      {
        ldef.prepend("enum ");
      }
    }
    int i=0,l;
    static QRegExp r("@[0-9]+");

    if (isEnumValue()) return;

    ol.pushGeneratorState();

    bool hasHtmlHelp = Config_getBool("GENERATE_HTML") && Config_getBool("GENERATE_HTMLHELP");
    HtmlHelp *htmlHelp = 0;
    if (hasHtmlHelp) htmlHelp = HtmlHelp::getInstance();

    if ((isVariable() || isTypedef()) && (i=r.match(ldef,0,&l))!=-1)
    {
      // find enum type and insert it in the definition
      MemberListIterator vmli(*ml);
      MemberDef *vmd;
      bool found=FALSE;
      for ( ; (vmd=vmli.current()) && !found ; ++vmli)
      {
        if (vmd->isEnumerate() && ldef.mid(i,l)==vmd->name())
        {
          ol.startDoxyAnchor(cfname,cname,anchor(),doxyName);
          ol.startMemberDoc(cname,name(),anchor(),name());
          if (hasHtmlHelp)
          {
            htmlHelp->addIndexItem(cname,name(),cfname,anchor());
          }
          linkifyText(TextGeneratorOLImpl(ol),scopeName,name(),ldef.left(i));
          ol+=*vmd->enumDecl();
          linkifyText(TextGeneratorOLImpl(ol),scopeName,name(),ldef.right(ldef.length()-i-l));

          found=TRUE;
        }
      }
      if (!found) // anonymous compound
      {
        //printf("Anonymous compound `%s'\n",cname.data());
        ol.startDoxyAnchor(cfname,cname,anchor(),doxyName);
        ol.startMemberDoc(cname,name(),anchor(),name());
        if (hasHtmlHelp)
        {
          htmlHelp->addIndexItem(cname,name(),cfname,anchor());
        }
        // strip anonymous compound names from definition
        int si=ldef.find(' '),pi,ei=i+l;
        if (si==-1) si=0;
        while ((pi=r.match(ldef,i+l,&l))!=-1) ei=i=pi+l;
        // first si characters of ldef contain compound type name
        ol.startMemberDocName();
        ol.docify(ldef.left(si));
        ol.docify(" { ... } ");
        // last ei characters of ldef contain pointer/reference specifiers
        int ni=ldef.find("::",si);
        if (ni>=ei) ei=ni+2;
        linkifyText(TextGeneratorOLImpl(ol),scopeName,name(),ldef.right(ldef.length()-ei));
      }
    }
    else // not an enum value
    {
      ol.startDoxyAnchor(cfname,cname,anchor(),doxyName);
      ol.startMemberDoc(cname,name(),anchor(),name());
      if (hasHtmlHelp)
      {
        htmlHelp->addIndexItem(cname,name(),cfname,anchor());
      }

      ClassDef *cd=getClassDef();
      if (!Config_getBool("HIDE_SCOPE_NAMES"))
      {
        bool first=TRUE;
        if (m_defTmpArgLists) 
          // definition has explicate template parameter declarations
        {
          QListIterator<ArgumentList> ali(*m_defTmpArgLists);
          ArgumentList *tal;
          for (ali.toFirst();(tal=ali.current());++ali)
          {
            if (tal->count()>0)
            {
              if (!first) ol.docify(" ");
              ol.startMemberDocPrefixItem();
              writeTemplatePrefix(ol,tal);
              ol.endMemberDocPrefixItem();
            }
          }
        }
        else
        {
          if (cd)
          {
            QList<ArgumentList> tempParamLists;
            cd->getTemplateParameterLists(tempParamLists);
            //printf("#tempParamLists=%d\n",tempParamLists.count());
            QListIterator<ArgumentList> ali(tempParamLists);
            ArgumentList *tal;
            for (ali.toFirst();(tal=ali.current());++ali)
            {
              if (tal->count()>0)
              {
                if (!first) ol.docify(" ");
                ol.startMemberDocPrefixItem();
                writeTemplatePrefix(ol,tal);
                ol.endMemberDocPrefixItem();
              }
            }
          }
          if (tArgList) // function template prefix
          {
            ol.startMemberDocPrefixItem();
            writeTemplatePrefix(ol,tArgList);
            ol.endMemberDocPrefixItem();
          }
        }
      }
      ol.startMemberDocName();
      linkifyText(TextGeneratorOLImpl(ol),scopeName,name(),ldef);
      writeDefArgumentList(ol,cd,scopeName,this);
      if (hasOneLineInitializer()
          //!init.isEmpty() && initLines==0 && // one line initializer
          //   ((maxInitLines>0 && userInitLines==-1) || userInitLines>0) // enabled by default or explicitly
         ) // add initializer
      {
        if (!isDefine()) 
        {
          ol.docify(" = "); 
          linkifyText(TextGeneratorOLImpl(ol),scopeName,name(),init.simplifyWhiteSpace());
        }
        else 
        {
          ol.writeNonBreakableSpace(3);
          linkifyText(TextGeneratorOLImpl(ol),scopeName,name(),init);
        }
      }
      if (excpString()) // add exception list
      {
        ol.docify(" ");
        linkifyText(TextGeneratorOLImpl(ol),scopeName,name(),excpString());
      }
    }

    Specifier lvirt=virtualness();
    MemberDef *rmd=reimplements();
    while (rmd && lvirt==Normal)
    {
      lvirt = rmd->virtualness()==Normal ? Normal : Virtual;
      rmd  = rmd->reimplements();
    }

    if (protection()!=Public || lvirt!=Normal ||
        isFriend() || isRelated() || isExplicit() ||
        isMutable() || (isInline() && Config_getBool("INLINE_INFO")) ||
        isSignal() || isSlot() ||
        isStatic()
       )
    {
      // write the member specifier list
      ol.writeLatexSpacing();
      ol.startTypewriter();
      ol.docify(" [");
      QStrList sl;
      if (isFriend()) sl.append("friend");
      else if (isRelated()) sl.append("related");
      else
      {
        if      (Config_getBool("INLINE_INFO") && isInline())              
                                          sl.append("inline");
        if      (isExplicit())            sl.append("explicit");
        if      (isMutable())             sl.append("mutable");
        if      (isStatic())              sl.append("static");
        if      (protection()==Protected) sl.append("protected");
        else if (protection()==Private)   sl.append("private");
        if      (lvirt==Virtual)          sl.append("virtual");
        else if (lvirt==Pure)             sl.append("pure virtual");
        if      (isSignal())              sl.append("signal");
        if      (isSlot())                sl.append("slot");
      }
      const char *s=sl.first();
      while (s)
      {
        ol.docify(s);
        s=sl.next();
        if (s) ol.docify(", ");
      }
      ol.docify("]");
      ol.endTypewriter();
    }
    if (!isDefine() && argList) ol.endParameterList();
    ol.endMemberDoc();
    ol.endDoxyAnchor(cfname,anchor());
    ol.startIndent();
    
    ol.pushGeneratorState();
    ol.disable(OutputGenerator::RTF);
    ol.newParagraph();
    ol.popGeneratorState();

    /* write multi-line initializer (if any) */
    if (hasMultiLineInitializer()
        //initLines>0 && ((initLines<maxInitLines && userInitLines==-1) // implicitly enabled
        //                || initLines<userInitLines // explicitly enabled
        //               )
       )
    {
      //printf("md=%s initLines=%d init=`%s'\n",name().data(),initLines,init.data());
      ol.startBold();
      if (mtype==Define)
        parseText(ol,theTranslator->trDefineValue());
      else
        parseText(ol,theTranslator->trInitialValue());
      ol.endBold();
      initParseCodeContext();
      ol.startCodeFragment();
      parseCode(ol,scopeName,init,FALSE,0);
      ol.endCodeFragment();
    }
    
    /* write brief description */
    if (!briefDescription().isEmpty() && 
        (Config_getBool("REPEAT_BRIEF")  
         /* || (!Config_getBool("BRIEF_MEMBER_DESC") && documentation().isEmpty())*/
        ) /* || !annMemb */
       )  
    { 
      parseDoc(ol,m_defFileName,m_defLine,scopeName,name(),briefDescription());
      ol.newParagraph();
    }

    /* write detailed description */
    if (!documentation().isEmpty())
    { 
      parseDoc(ol,m_defFileName,m_defLine,scopeName,name(),documentation()+"\n");
      ol.pushGeneratorState();
      ol.disableAllBut(OutputGenerator::RTF);
      ol.newParagraph();
      ol.popGeneratorState();
    }

    //printf("***** argList=%p name=%s docs=%s hasDocs=%d\n",
    //     argList, 
    //     argList?argList->hasDocumentation():-1);
    if (argList && argList->hasDocumentation())
    {
      //printf("***** argumentList is documented\n");
      ol.startParamList(BaseOutputDocInterface::Param);
      parseText(ol,theTranslator->trParameters()+": ");
      ol.endDescTitle();
      ol.writeDescItem();
      ol.startDescTable();
      ArgumentListIterator ali(*argList);
      Argument *a;
      for (ali.toFirst();(a=ali.current());++ali)
      {
        if (a->hasDocumentation())
        {
          ol.startDescTableTitle();
          ol.docify(a->name);
          ol.endDescTableTitle();
          ol.startDescTableData();
          parseDoc(ol,m_defFileName,m_defLine,scopeName,name(),a->docs+"\n");
          ol.endDescTableData();
        }
      }
      ol.endDescTable();
      ol.endDescList();
    }
    
    if (isEnumerate())
    {
      bool first=TRUE;
      MemberList *fmdl=enumFieldList();
      if (fmdl)
      {
        MemberDef *fmd=fmdl->first();
        while (fmd)
        {
          if (fmd->isLinkable())
          {
            if (first)
            {
              //ol.newParagraph();
              ol.startDescList(BaseOutputDocInterface::EnumValues);
              parseText(ol,theTranslator->trEnumerationValues());
              ol.docify(":");
              ol.endDescTitle();
              ol.writeDescItem();
              //ol.startItemList();
              ol.startDescTable();
            }

            ol.addIndexItem(fmd->name(),cname);
            ol.addIndexItem(cname,fmd->name());

            if (Config_getBool("GENERATE_HTML") && Config_getBool("GENERATE_HTMLHELP"))
            {
              HtmlHelp::getInstance()->addIndexItem(cname,fmd->name(),cfname,fmd->anchor());
            }
            //ol.writeListItem();
            ol.startDescTableTitle();
            ol.startDoxyAnchor(cfname,cname,fmd->anchor(),fmd->name());
            first=FALSE;