Doxygen
Loading...
Searching...
No Matches
DocRef Class Referencefinal

Node representing a reference to some item. More...

#include <src/docnode.h>

Inheritance diagram for DocRef:
Collaboration diagram for DocRef:

Public Member Functions

 DocRef (DocParser *parser, DocNodeVariant *parent, const DString &target, const DString &context)
void parse (char cmdChar, const DString &cmdName)
DString file () const
DString relPath () const
DString ref () const
DString anchor () const
DString targetTitle () const
SectionType sectionType () const
bool hasLinkText () const
bool refToAnchor () const
bool refToSection () const
bool refToTable () const
bool isSubPage () const
Public Member Functions inherited from DocCompoundNode
 DocCompoundNode (DocParser *parser, DocNodeVariant *parent)
DocNodeList & children ()
const DocNodeList & children () const
Public Member Functions inherited from DocNode
 DocNode (DocParser *parser, DocNodeVariant *parent)
 ~DocNode ()=default
DocNodeVariant * parent ()
const DocNodeVariant * parent () const
DocNodeVariant * thisVariant ()
const DocNodeVariant * thisVariant () const
void setThisVariant (DocNodeVariant *thisVariant)
DocParser * parser ()
const DocParser * parser () const
void setParent (DocNodeVariant *parent)
bool isPreformatted () const

Private Attributes

RefType m_refType = Unknown
SectionType m_sectionType = SectionType::Anchor
bool m_isSubPage = false
DString m_file
DString m_relPath
DString m_ref
DString m_anchor
DString m_text

Additional Inherited Members

Protected Types inherited from DocNode
enum  RefType {
  Unknown , Anchor , Section , Table ,
  Requirement
}
Protected Member Functions inherited from DocNode
void setInsidePreformatted (bool p)

Detailed Description

Node representing a reference to some item.

Definition at line 786 of file docnode.h.

Constructor & Destructor Documentation

◆ DocRef()

DocRef::DocRef ( DocParser * parser,
DocNodeVariant * parent,
const DString & target,
const DString & context )

Definition at line 728 of file docnode.cpp.

728 :
730{
731 const Definition *compound = nullptr;
732 DString anchor;
733 AUTO_TRACE("target='{}',context='{}'",target,context);
734 ASSERT(!target.empty());
736 auto lang = parser->context.lang;
737 const SectionInfo *sec = SectionManager::instance().find(parser->context.prefix+target);
738 if (sec==nullptr && !parser->context.prefix.empty())
739 {
740 sec = SectionManager::instance().find(target);
741 }
742
743 if (sec==nullptr && getLanguageFromFileName(target)==SrcLangExt::Markdown) // lookup as markdown file
744 {
746 }
747 if (sec) // ref to section or anchor
748 {
749 PageDef *pd = nullptr;
750 int secLevel = sec->type().level();
751 if (secLevel==SectionType::Page)
752 {
753 pd = Doxygen::pageLinkedMap->find(target);
754 }
755 m_text = sec->title();
756 if (m_text.empty()) m_text = sec->label();
757
758 m_ref = sec->ref();
760 if (secLevel==SectionType::Anchor)
761 {
763 }
764 else if (secLevel==SectionType::Table)
765 {
767 }
768 else if (secLevel==SectionType::Requirement)
769 {
771 if (!Config_getBool(GENERATE_REQUIREMENTS))
772 {
773 m_file.clear(); // prevent link when there is no requirements page
774 }
775 }
776 else
777 {
779 }
780 m_isSubPage = pd && pd->hasParentPage();
781 if (secLevel!=SectionType::Page || m_isSubPage)
782 {
783 m_anchor = pd ? pd->getOutputFileBase() : sec->label();
784 }
785 m_sectionType = sec->type();
786 //printf("m_text=%s,m_ref=%s,m_file=%s,type=%d\n",
787 // qPrint(m_text),qPrint(m_ref),qPrint(m_file),m_refType);
788 AUTO_TRACE_EXIT("section");
789 return;
790 }
791 else if (Config_getBool(IMPLICIT_DIR_DOCS) && target.lower().endsWith("/readme.md"))
792 {
793 DString dirTarget = target.left(target.length() - 9); // strip readme.md part
794 const auto &dd = Doxygen::dirLinkedMap->find(dirTarget);
795 if (dd)
796 {
797 m_text = target;
798 m_file = dd->getOutputFileBase();
799 AUTO_TRACE_EXIT("directory");
800 return;
801 }
802 }
803 else if (resolveLink(context,target,true,&compound,anchor,lang,parser->context.prefix,
805 {
806 bool isFile = compound ?
807 (compound->definitionType()==Definition::TypeFile ||
808 compound->definitionType()==Definition::TypePage ? true : false) :
809 false;
810 bool isDir = compound && compound->definitionType()==Definition::TypeDir;
811 if (compound && lang==SrcLangExt::Markdown) lang = compound->getLanguage();
812 m_text = linkToText(lang,target,isFile || isDir);
814 if (compound && compound->isLinkable()) // ref to compound
815 {
816 if (anchor.empty() && /* compound link */
817 compound->definitionType()==Definition::TypeGroup && /* is group */
818 !toGroupDef(compound)->groupTitle().empty() /* with title */
819 )
820 {
821 m_text=(toGroupDef(compound))->groupTitle(); // use group's title as link
822 }
823 else if (compound->definitionType()==Definition::TypeMember &&
824 toMemberDef(compound)->isObjCMethod())
825 {
826 // Objective C Method
827 const MemberDef *member = toMemberDef(compound);
828 bool localLink = parser->context.memberDef ? member->getClassDef()==parser->context.memberDef->getClassDef() : false;
829 m_text = member->objCMethodName(localLink,parser->context.inSeeBlock);
830 }
831 else if (Config_getBool(HIDE_SCOPE_NAMES))
832 {
833 size_t funcPos = m_text.find('(');
834 if (funcPos!=DString::npos) // see issue #11834
835 {
836 m_text=stripScope(m_text.left(funcPos))+m_text.mid(funcPos);
837 }
838 else
839 {
841 }
842 }
843
844 m_file = compound->getOutputFileBase();
845 m_ref = compound->getReference();
846 //printf("isFile=%d compound=%s (%d)\n",isFile,qPrint(compound->name()),
847 // compound->definitionType());
848 AUTO_TRACE_EXIT("compound");
849 return;
850 }
851 else if (compound && compound->definitionType()==Definition::TypeFile &&
852 toFileDef(compound)->generateSourceFile()
853 ) // undocumented file that has source code we can link to
854 {
855 m_file = compound->getSourceFileBase();
856 m_ref = compound->getReference();
857 AUTO_TRACE_EXIT("source");
858 return;
859 }
860 else
861 {
862 AUTO_TRACE_EXIT("compound '{}' not linkable",compound?compound->name():"none");
863 }
864 }
865 m_text = target;
866 warn_doc_error(parser->context.fileName,parser->tokenizer.getLineNr(),"unable to resolve reference to '{}' for \\ref command",
867 target);
868}
void clear()
Definition dstring.h:214
DString mid(size_t index, size_t len=npos) const
Definition dstring.h:318
DString lower() const
Definition dstring.h:326
bool empty() const
Returns true iff the string is empty (std::string compatible alias for isEmpty()).
Definition dstring.h:148
static constexpr size_t npos
value used to indicate 'not found' or 'to the end of the string', matching std::string::npos
Definition dstring.h:178
size_t find(char c, size_t pos=0) const
Definition dstring.h:239
DString left(size_t len) const
Definition dstring.h:306
bool endsWith(const char *s) const
Definition dstring.h:617
size_t length() const
Returns the length of the string, not counting the 0-terminator.
Definition dstring.h:151
virtual SrcLangExt getLanguage() const =0
Returns the programming language this definition was written in.
virtual bool isLinkable() const =0
virtual DefType definitionType() const =0
virtual const DString & name() const =0
virtual DString getReference() const =0
virtual DString getSourceFileBase() const =0
virtual DString getOutputFileBase() const =0
DocCompoundNode(DocParser *parser, DocNodeVariant *parent)
Definition docnode.h:141
DocParser * parser()
Definition docnode.h:97
DocNodeVariant * parent()
Definition docnode.h:89
@ Unknown
Definition docnode.h:109
@ Table
Definition docnode.h:109
@ Requirement
Definition docnode.h:109
@ Section
Definition docnode.h:109
@ Anchor
Definition docnode.h:109
DocTokenizer tokenizer
DocParserContext context
SectionType m_sectionType
Definition docnode.h:805
DString m_ref
Definition docnode.h:809
DString anchor() const
Definition docnode.h:794
DString m_relPath
Definition docnode.h:808
DString m_anchor
Definition docnode.h:810
RefType m_refType
Definition docnode.h:804
DString m_text
Definition docnode.h:811
DString m_file
Definition docnode.h:807
bool m_isSubPage
Definition docnode.h:806
int getLineNr() const
static PageLinkedMap * pageLinkedMap
Definition doxygen.h:92
static DirLinkedMap * dirLinkedMap
Definition doxygen.h:120
const T * find(const std::string &key) const
Definition linkedmap.h:47
virtual DString objCMethodName(bool localLink, bool showStatic) const =0
virtual const ClassDef * getClassDef() const =0
virtual bool hasParentPage() const =0
DString fileName() const
Definition section.h:74
SectionType type() const
Definition section.h:71
DString title() const
Definition section.h:70
DString ref() const
Definition section.h:72
DString label() const
Definition section.h:69
static SectionManager & instance()
returns a reference to the singleton
Definition section.h:179
static constexpr int Anchor
Definition section.h:40
static constexpr int Table
Definition section.h:41
constexpr int level() const
Definition section.h:46
static constexpr int Requirement
Definition section.h:42
static constexpr int Page
Definition section.h:31
#define Config_getBool(name)
Definition config.h:33
static const FileDef * currentFileDef(const DocParser *parser)
Definition docnode.cpp:89
#define AUTO_TRACE(...)
Definition docnode.cpp:53
#define AUTO_TRACE_EXIT(...)
Definition docnode.cpp:55
static DString stripKnownExtensions(const DString &text)
Definition docnode.cpp:119
FileDef * toFileDef(Definition *d)
Definition filedef.cpp:2054
GroupDef * toGroupDef(Definition *d)
DString markdownFileNameToId(const DString &fileName)
processes string s and converts markdown into doxygen/html commands.
MemberDef * toMemberDef(Definition *d)
#define ASSERT(x)
Definition message.h:142
#define warn_doc_error(file, line, fmt,...)
Definition message.h:112
SrcLangExt lang
Definition docparser_p.h:84
const MemberDef * memberDef
Definition docparser_p.h:79
bool resolveLink(const DString &scName, const DString &lr, bool, const Definition **resContext, DString &resAnchor, SrcLangExt lang, const DString &prefix, const FileDef *currentFile)
Definition util.cpp:2316
DString stripScope(const DString &name)
Definition util.cpp:3118
SrcLangExt getLanguageFromFileName(const DString &fileName, SrcLangExt defLang)
Definition util.cpp:4177
DString linkToText(SrcLangExt lang, const DString &link, bool ignoreDots)
Definition util.cpp:2273

References DocNode::Anchor, SectionType::Anchor, anchor(), ASSERT, AUTO_TRACE, AUTO_TRACE_EXIT, DString::clear(), Config_getBool, DocParser::context, currentFileDef(), Definition::definitionType(), Doxygen::dirLinkedMap, DString::empty(), DString::endsWith(), DocParserContext::fileName, SectionInfo::fileName(), DString::find(), LinkedMap< T, Hash, KeyEqual, Map >::find(), MemberDef::getClassDef(), Definition::getLanguage(), getLanguageFromFileName(), DocTokenizer::getLineNr(), Definition::getOutputFileBase(), Definition::getReference(), Definition::getSourceFileBase(), PageDef::hasParentPage(), DocParserContext::inSeeBlock, SectionManager::instance(), Definition::isLinkable(), SectionInfo::label(), DocParserContext::lang, DString::left(), DString::length(), SectionType::level(), linkToText(), DString::lower(), m_anchor, m_file, m_isSubPage, m_ref, m_refType, m_relPath, m_sectionType, m_text, markdownFileNameToId(), DocParserContext::memberDef, DString::mid(), Definition::name(), DString::npos, MemberDef::objCMethodName(), SectionType::Page, Doxygen::pageLinkedMap, DocNode::parent(), DocNode::parser(), DocParserContext::prefix, SectionInfo::ref(), DocParserContext::relPath, DocNode::Requirement, SectionType::Requirement, resolveLink(), DocNode::Section, stripKnownExtensions(), stripScope(), DocNode::Table, SectionType::Table, SectionInfo::title(), toFileDef(), toGroupDef(), DocParser::tokenizer, toMemberDef(), SectionInfo::type(), Definition::TypeDir, Definition::TypeFile, Definition::TypeGroup, Definition::TypeMember, Definition::TypePage, DocNode::Unknown, and warn_doc_error.

Member Function Documentation

◆ anchor()

◆ file()

◆ hasLinkText()

bool DocRef::hasLinkText ( ) const
inline

◆ isSubPage()

bool DocRef::isSubPage ( ) const
inline

◆ parse()

void DocRef::parse ( char cmdChar,
const DString & cmdName )

Definition at line 911 of file docnode.cpp.

912{
913 AUTO_TRACE();
914 auto ns = AutoNodeStack(parser(),thisVariant());
915 char cmdCharStr[2] = { cmdChar, 0 };
916
917 Token tok = parser()->tokenizer.lex();
918 while (!tok.is_any_of(TokenRetval::TK_NONE, TokenRetval::TK_EOF))
919 {
920 if (!parser()->defaultHandleToken(thisVariant(),tok,children()))
921 {
922 switch (tok.value())
923 {
924 case TokenRetval::TK_HTMLTAG:
925 break;
926 default:
927 parser()->errorHandleDefaultToken(thisVariant(),tok,children(),cmdCharStr+cmdName);
928 break;
929 }
930 }
931 tok=parser()->tokenizer.lex();
932 }
933
934 if (children().empty() && !m_text.empty())
935 {
936 DString text = m_text;
937 if (parser()->context.insideHtmlLink)
938 {
939 // we already in a link/title only output anchor
940 text = m_anchor;
941 warn_doc_error(parser()->context.fileName,parser()->tokenizer.getLineNr(),
942 "Potential recursion while resolving {:c}{} command!",cmdChar,cmdName);
943 }
945 { DocParser::AutoSaveContext saveContext(*parser());
947 }
951 }
952
954}
DocNodeVariant * thisVariant()
Definition docnode.h:92
void handlePendingStyleCommands(DocNodeVariant *parent, DocNodeList &children, size_t numberOfElementsToClose=0)
void errorHandleDefaultToken(DocNodeVariant *parent, Token tok, DocNodeList &children, const DString &txt)
Token internalValidatingParseDoc(DocNodeVariant *parent, DocNodeList &children, const DString &doc)
void setStatePara()
TokenRetval value() const
bool is_any_of(ARGS... args) const
static void flattenParagraphs(DocNodeVariant *root, DocNodeList &children)
Definition docnode.cpp:879

References AUTO_TRACE, DocCompoundNode::children(), DocParser::context, DString::empty(), DocParser::errorHandleDefaultToken(), flattenParagraphs(), DocParser::handlePendingStyleCommands(), DocParserContext::insideHtmlLink, DocParser::internalValidatingParseDoc(), Token::is_any_of(), DocTokenizer::lex(), m_anchor, m_text, DocNode::parser(), DocTokenizer::setStatePara(), DocNode::thisVariant(), DocParser::tokenizer, Token::value(), and warn_doc_error.

◆ ref()

◆ refToAnchor()

bool DocRef::refToAnchor ( ) const
inline

Definition at line 798 of file docnode.h.

798{ return m_refType==Anchor; }

References DocNode::Anchor, and m_refType.

Referenced by PrintDocVisitor::operator()().

◆ refToSection()

bool DocRef::refToSection ( ) const
inline

Definition at line 799 of file docnode.h.

799{ return m_refType==Section; }

References m_refType, and DocNode::Section.

Referenced by LatexDocVisitor::operator()(), and PrintDocVisitor::operator()().

◆ refToTable()

bool DocRef::refToTable ( ) const
inline

Definition at line 800 of file docnode.h.

800{ return m_refType==Table; }

References m_refType, and DocNode::Table.

Referenced by LatexDocVisitor::operator()(), and PrintDocVisitor::operator()().

◆ relPath()

DString DocRef::relPath ( ) const
inline

Definition at line 792 of file docnode.h.

792{ return m_relPath; }

References m_relPath.

Referenced by HtmlDocVisitor::operator()().

◆ sectionType()

SectionType DocRef::sectionType ( ) const
inline

Definition at line 796 of file docnode.h.

796{ return m_sectionType; }

References m_sectionType.

Referenced by LatexDocVisitor::operator()().

◆ targetTitle()

Member Data Documentation

◆ m_anchor

DString DocRef::m_anchor
private

Definition at line 810 of file docnode.h.

Referenced by anchor(), DocRef(), and parse().

◆ m_file

DString DocRef::m_file
private

Definition at line 807 of file docnode.h.

Referenced by DocRef(), and file().

◆ m_isSubPage

bool DocRef::m_isSubPage = false
private

Definition at line 806 of file docnode.h.

Referenced by DocRef(), and isSubPage().

◆ m_ref

DString DocRef::m_ref
private

Definition at line 809 of file docnode.h.

Referenced by DocRef(), and ref().

◆ m_refType

RefType DocRef::m_refType = Unknown
private

Definition at line 804 of file docnode.h.

Referenced by DocRef(), refToAnchor(), refToSection(), and refToTable().

◆ m_relPath

DString DocRef::m_relPath
private

Definition at line 808 of file docnode.h.

Referenced by DocRef(), and relPath().

◆ m_sectionType

SectionType DocRef::m_sectionType = SectionType::Anchor
private

Definition at line 805 of file docnode.h.

Referenced by DocRef(), and sectionType().

◆ m_text

DString DocRef::m_text
private

Definition at line 811 of file docnode.h.

Referenced by DocRef(), parse(), and targetTitle().


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