RequirementManager Class Reference

#include <src/requirement.h>

Classes
class	Private

Public Member Functions
void	addRequirement (Entry *e)
void	generatePage ()
void	writeTagFile (TextStream &tagFile)
void	addRequirementRefsForSymbol (const Definition *symbol)
const RequirementIntf *	find (const DString &reqId) const
void	writeRef (OutputList &ol, const RequirementRef &ref)
bool	hasRequirements () const
RequirementIntfList	requirements () const
const PageDef *	requirementsPage () const

Static Public Member Functions
static RequirementManager &	instance ()

Private Member Functions
	RequirementManager ()

Private Attributes
std::unique_ptr< Private >	p

Detailed Description

Definition at line 79 of file requirement.h.

Constructor & Destructor Documentation

RequirementManager()

RequirementManager::RequirementManager ( )

private

Definition at line 107 of file requirement.cpp.

                                       : p(std::make_unique<Private>())
{
}

References p.

Referenced by instance().

Member Function Documentation

addRequirement()

void RequirementManager::addRequirement

(

Entry *

e

)

Definition at line 116 of file requirement.cpp.

{
  DString tagFile;
  DString extPage;
  if (!Config_getBool(GENERATE_REQUIREMENTS)) // still record the requirement, so we can refer to it.
  {
    if (e->tagInfo())
    {
      //printf("External requirement %s title=%s fileName=%s tagName=%s anchor=%s\n",
      //    qPrint(e->name),qPrint(e->type),qPrint(e->tagInfo()->fileName),qPrint(e->tagInfo()->tagName),qPrint(e->tagInfo()->anchor));
      tagFile = e->tagInfo()->tagName;
      extPage = e->tagInfo()->fileName;
      // register requirement id as anchor; for non-external links this is
      // done in commentscan.l in the comment block containing the @requirement command
      SectionManager::instance().add(e->name,"requirements",1,e->type,SectionType::Requirement,1);
    }
    p->requirements.add(e->name, e->fileName, e->startLine, e->type, e->doc, tagFile, extPage);
  }
  else
  {
    if (p->reqPageDef==nullptr)
    {
      p->reqPageDef = addRelatedPage("requirements",                      // name
          theTranslator->trRequirements(),     // ptitle
          DString(),                          // doc
          "requirements",                      // fileName
          1,                                   // docLine
          1                                    // startLine
          );
    }
    //printf("requirement ID=%s title='%s' file=%s line=%d brief='%s' doc='%s'\n",
    //    qPrint(e->name), qPrint(e->type), qPrint(e->fileName), e->startLine, qPrint(e->brief), qPrint(e->doc));
    DString title = parseCommentAsText(p->reqPageDef,nullptr,e->type,e->fileName,e->startLine);
    DString doc = e->doc;
    if (e->tagInfo())
    {
      //printf("External requirement %s title=%s fileName=%s tagName=%s anchor=%s\n",
      //    qPrint(e->name),qPrint(e->type),qPrint(e->tagInfo()->fileName),qPrint(e->tagInfo()->tagName),qPrint(e->tagInfo()->anchor));
      tagFile = e->tagInfo()->tagName;
      extPage = e->tagInfo()->fileName;
      // register requirement id as anchor; for non-external links this is
      // done in commentscan.l in the comment block containing the @requirement command
      SectionManager::instance().add(e->name,"requirements",1,title,SectionType::Anchor,1);
    }
    if (!e->brief.empty())
    {
      doc.prepend(e->brief+"\n<p>");
    }
    p->requirements.add(e->name, e->fileName, e->startLine, title, doc, tagFile, extPage);
 
    p->reqPageDef->setRefItems(e->sli);
  }
}

References SectionManager::add(), addRelatedPage(), SectionType::Anchor, Entry::brief, Config_getBool, Entry::doc, DString::empty(), Entry::fileName, TagInfo::fileName, SectionManager::instance(), Entry::name, p, parseCommentAsText(), DString::prepend(), SectionType::Requirement, Entry::sli, Entry::startLine, Entry::tagInfo(), TagInfo::tagName, theTranslator, Translator::trRequirements(), and Entry::type.

Referenced by buildRequirementsList().

addRequirementRefsForSymbol()

void RequirementManager::addRequirementRefsForSymbol

(

const Definition *

symbol

)

Definition at line 337 of file requirement.cpp.

{
  for (const auto &ref : symbol->requirementReferences())
  {
    Requirement *req = p->requirements.find(ref.reqId());
    if (req)
    {
      //printf("adding reference from %s to requirement %s\n",qPrint(symbol->name()),qPrint(ref.reqId()));
      switch (ref.type())
      {
        case RequirementRefType::Satisfies: req->addSatisfiedBy(symbol); break;
        case RequirementRefType::Verifies:  req->addVerifiedBy(symbol);   break;
      }
    }
    else
    {
      warn(ref.file(),ref.line(),"Reference to unknown requirement '{}' found",ref.reqId());
      // invalid reference (file, and line needed)
    }
  }
}

References Requirement::addSatisfiedBy(), Requirement::addVerifiedBy(), p, Definition::requirementReferences(), Satisfies, Verifies, and warn.

Referenced by ClassDefImpl::addRequirementReferences(), ConceptDefImpl::addRequirementReferences(), DirDefImpl::addRequirementReferences(), FileDefImpl::addRequirementReferences(), GroupDefImpl::addRequirementReferences(), MemberDefImpl::addRequirementReferences(), ModuleDefImpl::addRequirementReferences(), NamespaceDefImpl::addRequirementReferences(), and PageDefImpl::addRequirementReferences().

find()

const RequirementIntf * RequirementManager::find

(

const DString &

reqId

)

const

Definition at line 332 of file requirement.cpp.

{
  return p->requirements.find(reqId);
}

References p.

Referenced by generatePage(), and writeRef().

generatePage()

void RequirementManager::generatePage

(

)

Definition at line 185 of file requirement.cpp.

{
  AUTO_TRACE("#requirements={}",p->requirements.size());
  if (!Config_getBool(GENERATE_REQUIREMENTS) || p->requirements.empty()) return;
  std::vector<const SectionInfo*> anchors;
  std::stable_sort(p->requirements.begin(),p->requirements.end(),
                   [](const auto &left,const auto &right) { return dstricmp(left->id(),right->id()) < 0; });
  DString doc = "<table class=\"doxtable reqlist\">";
  doc.reserve(10*1024); // prevent too many reallocs
  doc += "<tr><th>";
  doc += theTranslator->trRequirementID();
  doc += "</th><th>";
  doc += "</th>";
  using RequirementPtrVector = std::vector<const Requirement*>;
  RequirementPtrVector missingSatisfiedRef, missingVerifiedRef;
  for (const auto &req : p->requirements) // TODO: filter out external references?
  {
    if (const SectionInfo *si = SectionManager::instance().find(req->id()); si!=nullptr)
    {
      anchors.push_back(si);
    }
    doc += "<tr><td valign=\"top\">";
    doc += " \\ifile \""+req->file()+"\" \\iline "+DString().setNum(req->line())+" ";
    doc += "\\anchor ";
    doc += req->id();
    doc += " ";
    doc += "<span class=\"req_id\">";
    if (DString tagFile = req->getTagFile(); !tagFile.empty())
    {
      //printf("tagFile=%s extPage=%s\n",qPrint(tagFile),qPrint(req->getExtPage()));
      doc += "<a href=\"";
      doc += createHtmlUrl(DString(),tagFile,false,req->getExtPage(),req->id());
      doc +="\">"+req->id()+"</a>";
    }
    else
    {
      doc += req->id();
    }
    doc += "</span> ";
    doc += "</td><td>";
    doc += "<div class=\"req_title\">"+req->title()+"</div>";
    doc += "<p/><div class=\"req_docs\">";
    doc += req->doc();
    req->sortReferences();
    auto symToString = [](const Definition *sym)
    {
      DString symName = sym->qualifiedName();
      if (sym->definitionType()==Definition::TypeMember)
      {
        const MemberDef *md = toMemberDef(sym);
        if (!md->isObjCMethod() && md->isFunctionOrSignalSlot()) symName += "()";
      }
      return symName;
    };
    int numSatisfiedBy = static_cast<int>(req->satisfiedBy().size());
    if (numSatisfiedBy>0)
    {
      doc += "<p><div class=\"satisfiedby\">";
      doc += theTranslator->trSatisfiedBy(
                 writeMarkerList(theTranslator->trWriteList(numSatisfiedBy).str(),
                     numSatisfiedBy,
                     [&symToString, &refs = req->satisfiedBy()](size_t entryIndex) {
                       return symToString(refs[entryIndex]);
                     }));
      doc += "</div></p>";
    }
    else
    {
      missingSatisfiedRef.push_back(req.get());
    }
    int numVerifiedBy = static_cast<int>(req->verifiedBy().size());
    if (numVerifiedBy>0)
    {
      doc += "<p><div class=\"verifiedby\">";
      doc += theTranslator->trVerifiedBy(
                 writeMarkerList(theTranslator->trWriteList(numVerifiedBy).str(),
                     numVerifiedBy,
                     [&symToString, &refs = req->verifiedBy()](size_t entryIndex) {
                       return symToString(refs[entryIndex]);
                     }));
      doc += "</div></p>";
    }
    else
    {
      missingVerifiedRef.push_back(req.get());
    }
    doc += "\n</div></td></tr>\n";
  }
  doc += "</table>\n";
 
  //------------
  doc += " \\ifile \"requirements\" \\iline 1\n";
 
  auto writeMissingRef = [&doc,&anchors](const RequirementPtrVector &reqs,
                                         const char *label,const DString &section,const DString &text)
  {
    if (!reqs.empty())
    {
      SectionManager &sm = SectionManager::instance();
      const SectionInfo *si = sm.add(DString("missing_")+label,"requirements",1,section,SectionType::Section,1);
      anchors.push_back(si);
      doc += "\\htmlonly <div class=\"missing_";
      doc += label;
      doc += "\">\\endhtmlonly\n";
      doc += DString("@section missing_")+label+" "+section+"\n"+text+"\n";
      doc += "\\htmlonly </div>\\endhtmlonly\n";
    }
  };
 
  // write list of requirements that do not have a satisfies relation
  auto traceInfo = Config_getEnum(REQ_TRACEABILITY_INFO);
  int numMissingSatisfied = static_cast<int>(missingSatisfiedRef.size());
  if ((traceInfo==REQ_TRACEABILITY_INFO_t::YES || traceInfo==REQ_TRACEABILITY_INFO_t::UNSATISFIED_ONLY) && numMissingSatisfied>0)
  {
    writeMissingRef(missingSatisfiedRef,
                    "satisfies",
                    theTranslator->trUnsatisfiedRequirements(),
                    theTranslator->trUnsatisfiedRequirementsText(numMissingSatisfied==1,
                     writeMarkerList(theTranslator->trWriteList(numMissingSatisfied).str(),
                       numMissingSatisfied,
                       [&missingSatisfiedRef](size_t entryIndex) {
                         DString id = missingSatisfiedRef[entryIndex]->id();
                         return "@ref "+id + " \""+id+"\"";
                       })));
  }
 
  // write list of requirements that do not have a verifies relation
  int numMissingVerified = static_cast<int>(missingVerifiedRef.size());
  if ((traceInfo==REQ_TRACEABILITY_INFO_t::YES || traceInfo==REQ_TRACEABILITY_INFO_t::UNVERIFIED_ONLY) && numMissingVerified>0)
  {
    writeMissingRef(missingVerifiedRef,
                    "verifies",
                    theTranslator->trUnverifiedRequirements(),
                    theTranslator->trUnverifiedRequirementsText(numMissingVerified==1,
                     writeMarkerList(theTranslator->trWriteList(numMissingVerified).str(),
                       numMissingVerified,
                       [&missingVerifiedRef](size_t entryIndex) {
                         DString id = missingVerifiedRef[entryIndex]->id();
                         return "@ref "+id + " \""+id+"\"";
                       })));
  }
 
  AUTO_TRACE_ADD("doc=[[\n{}\n]]\n",doc);
  p->reqPageDef->setDocumentation(doc,"requirements",1,false);
  p->reqPageDef->addSectionsToDefinition(anchors);
}

References SectionManager::add(), AUTO_TRACE, AUTO_TRACE_ADD, Config_getBool, Config_getEnum, createHtmlUrl(), DString::empty(), find(), SectionManager::instance(), MemberDef::isFunctionOrSignalSlot(), MemberDef::isObjCMethod(), p, DString::reserve(), SectionType::Section, DString::setNum(), DString::str(), theTranslator, toMemberDef(), Translator::trRequirementID(), Translator::trSatisfiedBy(), Translator::trUnsatisfiedRequirements(), Translator::trUnsatisfiedRequirementsText(), Translator::trUnverifiedRequirements(), Translator::trUnverifiedRequirementsText(), Translator::trVerifiedBy(), Translator::trWriteList(), Definition::TypeMember, and writeMarkerList().

Referenced by parseInput().

hasRequirements()

bool RequirementManager::hasRequirements

(

)

const

Definition at line 170 of file requirement.cpp.

{
  return !p->requirements.empty();
}

References p.

instance()

RequirementManager & RequirementManager::instance ( )

static

Definition at line 101 of file requirement.cpp.

{
  static RequirementManager s_instance;
  return s_instance;
}

References RequirementManager().

Referenced by ClassDefImpl::addRequirementReferences(), ConceptDefImpl::addRequirementReferences(), DirDefImpl::addRequirementReferences(), FileDefImpl::addRequirementReferences(), GroupDefImpl::addRequirementReferences(), MemberDefImpl::addRequirementReferences(), ModuleDefImpl::addRequirementReferences(), NamespaceDefImpl::addRequirementReferences(), PageDefImpl::addRequirementReferences(), buildRequirementsList(), generateXML(), generateXMLForRequirement(), generateXMLForRequirements(), DocParser::handleLinkedWord(), parseInput(), writeRef(), and writeTagFile().

requirements()

RequirementIntfList RequirementManager::requirements

(

)

const

Definition at line 175 of file requirement.cpp.

{
  RequirementIntfList result;
  for (const auto &req : p->requirements)
  {
    result.push_back(req.get());
  }
  return result;
}

References p.

Referenced by generateXMLForRequirements().

requirementsPage()

const PageDef * RequirementManager::requirementsPage

(

)

const

Definition at line 111 of file requirement.cpp.

{
  return p->reqPageDef;
}

References p.

Referenced by generateXMLForRequirement().

writeRef()

void RequirementManager::writeRef	(	OutputList &	ol,
		const RequirementRef &	ref )

Definition at line 360 of file requirement.cpp.

{
  if (!Config_getBool(GENERATE_REQUIREMENTS)) return;
  if (const RequirementIntf *req = RequirementManager::instance().find(ref.reqId()); req!=nullptr)
  {
    DString title = ref.reqId();
    if (!ref.title().empty())
    {
      title +=" (";
      title += parseCommentAsText(p->reqPageDef,nullptr,ref.title(),ref.file(),ref.line());
      title +=")";
    }
    else if (!req->title().empty())
    {
      title += " (";
      title += req->title();
      title += ")";
    }
    else
    {
      title = ref.reqId();
    }
    ol.writeObjectLink(DString(),req->getOutputFileBase(),ref.reqId(),title);
  }
  else
  {
    ol.docify(ref.reqId());
  }
}

References Config_getBool, OutputList::docify(), DString::empty(), RequirementRef::file(), find(), instance(), RequirementRef::line(), p, parseCommentAsText(), RequirementRef::reqId(), RequirementRef::title(), and OutputList::writeObjectLink().

writeTagFile()

void RequirementManager::writeTagFile

(

TextStream &

tagFile

)

Definition at line 390 of file requirement.cpp.

{
  if (!Config_getBool(GENERATE_REQUIREMENTS)) return;
  if (!p->requirements.empty())
  {
    for (const auto &req : p->requirements)
    {
      tagFile << "  <compound kind=\"requirement\">\n";
      tagFile << "    <id>" << req->id() << "</id>\n";
      tagFile << "    <title>" << convertToXML(req->title()) << "</title>\n";
      DString fn = req->getOutputFileBase();
      addHtmlExtensionIfMissing(fn);
      tagFile << "    <filename>" << fn << "</filename>\n";
      tagFile << "  </compound>\n";
    }
  }
}

References addHtmlExtensionIfMissing(), Config_getBool, convertToXML(), and p.

Referenced by writeTagFile().

Member Data Documentation

p

std::unique_ptr<Private> RequirementManager::p

private

Definition at line 95 of file requirement.h.

Referenced by addRequirement(), addRequirementRefsForSymbol(), find(), generatePage(), hasRequirements(), RequirementManager(), requirements(), requirementsPage(), writeRef(), and writeTagFile().

---

The documentation for this class was generated from the following files:

• src/requirement.h
• src/requirement.cpp