copydetails command copies unambiguous metadata

include/mrdocs/Corpus.hpp

@@ -90,12 +90,12 @@ class MRDOCS_VISIBLE
     /** Return the Info for the matching string in a given context.
     */
     virtual
-    Info const*
+    Expected<Info const*>
     lookup(SymbolID const& context, std::string_view name) const = 0;
 
     /** Return the Info for the matching string in the global context.
     */
-    Info const*
+    Expected<Info const*>
     lookup(std::string_view name) const
     {
         return lookup(SymbolID::global, name);

include/mrdocs/Metadata/Info.hpp

@@ -355,6 +355,15 @@ tag_invoke(
     });
 }
 
+inline
+OptionalLocation
+getPrimaryLocation(Info const& I)
+{
+    return getPrimaryLocation(
+        dynamic_cast<SourceInfo const&>(I),
+        I.isRecord() || I.isEnum());
+}
+
 } // clang::mrdocs
 
 #endif

include/mrdocs/Metadata/Source.hpp

@@ -144,7 +144,7 @@ merge(SourceInfo& I, SourceInfo&& Other);
 
 MRDOCS_DECL
 OptionalLocation
-getPrimaryLocation(SourceInfo const& I);
+getPrimaryLocation(SourceInfo const& I, bool preferDefinition);
 
 void
 tag_invoke(

src/lib/AST/ASTVisitor.cpp

@@ -531,10 +531,24 @@ void
 ASTVisitor::
 populate(Info& I, bool const isNew, DeclTy const* D)
 {
-    // Populate the documentation
-    bool const isDocumented = generateJavadoc(I.javadoc, D);
+    populate(I.javadoc, D);
+    populate(dynamic_cast<SourceInfo&>(I), D);
 
-    // Populate the source info
+    // All other information is redundant if the symbol is not new
+    MRDOCS_CHECK_OR(isNew);
+
+    // These should already have been populated by traverseImpl
+    MRDOCS_ASSERT(I.id);
+    MRDOCS_ASSERT(I.Kind != InfoKind::None);
+
+    I.Name = extractName(D);
+}
+
+template <std::derived_from<Decl> DeclTy>
+void
+ASTVisitor::
+populate(SourceInfo& I, DeclTy const* D)
+{
     clang::SourceLocation Loc = D->getBeginLoc();
     if (Loc.isInvalid())
     {
@@ -544,17 +558,26 @@ populate(Info& I, bool const isNew, DeclTy const* D)
     {
         populate(
             dynamic_cast<SourceInfo&>(I),
-            Loc, isDefinition(D), isDocumented);
+            Loc,
+            isDefinition(D),
+            D->getASTContext().getRawCommentForDeclNoCache(D));
     }
+}
 
-    // All other information is redundant if the symbol is not new
-    MRDOCS_CHECK_OR(isNew);
-
-    // These should already have been populated by traverseImpl
-    MRDOCS_ASSERT(I.id);
-    MRDOCS_ASSERT(I.Kind != InfoKind::None);
-
-    I.Name = extractName(D);
+bool
+ASTVisitor::
+populate(
+    std::optional<Javadoc>& javadoc,
+    Decl const* D)
+{
+    RawComment const* RC =
+        D->getASTContext().getRawCommentForDeclNoCache(D);
+    MRDOCS_CHECK_OR(RC, false);
+    comments::FullComment* FC =
+        RC->parse(D->getASTContext(), &sema_.getPreprocessor(), D);
+    MRDOCS_CHECK_OR(FC, false);
+    parseJavadoc(javadoc, FC, D, config_, diags_);
+    return true;
 }
 
 void
@@ -686,6 +709,13 @@ populate(RecordInfo& I, ClassTemplateSpecializationDecl const* D)
     populate(I, cast<CXXRecordDecl>(D));
 }
 
+void
+ASTVisitor::
+populate(RecordInfo& I, ClassTemplatePartialSpecializationDecl const* D)
+{
+    populate(I, dynamic_cast<ClassTemplateSpecializationDecl const*>(D));
+}
+
 void
 ASTVisitor::
 populate(
@@ -1023,6 +1053,13 @@ populate(VariableInfo& I, VarTemplateSpecializationDecl const* D)
     populate(I, cast<VarDecl>(D));
 }
 
+void
+ASTVisitor::
+populate(VariableInfo& I, VarTemplatePartialSpecializationDecl const* D)
+{
+    populate(I, dynamic_cast<VarTemplateSpecializationDecl const*>(D));
+}
+
 void
 ASTVisitor::
 populate(
@@ -1883,22 +1920,6 @@ qualifiedName(NamedDecl const* ND) const
     return name;
 }
 
-bool
-ASTVisitor::
-generateJavadoc(
-    std::optional<Javadoc>& javadoc,
-    Decl const* D)
-{
-    RawComment const* RC =
-        D->getASTContext().getRawCommentForDeclNoCache(D);
-    MRDOCS_CHECK_OR(RC, false);
-    comments::FullComment* FC =
-        RC->parse(D->getASTContext(), &sema_.getPreprocessor(), D);
-    MRDOCS_CHECK_OR(FC, false);
-    parseJavadoc(javadoc, FC, D, config_, diags_);
-    return true;
-}
-
 Polymorphic<TypeInfo>
 ASTVisitor::
 toTypeInfo(QualType const qt, TraversalMode const mode)
@@ -3341,9 +3362,9 @@ checkUndocumented(
     }
     // If the symbol is undocumented, check if we haven't seen a
     // documented version before.
-    auto const it = info_.find(id);
-    if (it != info_.end() &&
-        it->get()->javadoc)
+    if (auto const infoIt = info_.find(id);
+        infoIt != info_.end() &&
+        infoIt->get()->javadoc)
     {
         return {};
     }
@@ -3352,7 +3373,17 @@ checkUndocumented(
     // symbols we've seen so far in this translation unit.
     if (config_->warnIfUndocumented)
     {
-        undocumented_.insert({id, extractName(D)});
+        auto const undocIt = undocumented_.find(id);
+        if (undocIt == undocumented_.end())
+        {
+            InfoKind const kind = InfoTy::kind_id;
+            undocumented_.insert(UndocumentedInfo{id, extractName(D), kind});
+        }
+        // Populate the location
+        auto handle = undocumented_.extract(undocIt);
+        UndocumentedInfo& UI = handle.value();
+        populate(dynamic_cast<SourceInfo&>(UI), D);
+        undocumented_.insert(std::move(handle));
     }
     return Unexpected(Error("Undocumented"));
 }

src/lib/AST/ASTVisitor.hpp

@@ -484,6 +484,24 @@ class ASTVisitor
     void
     populate(Info& I, bool isNew, DeclTy const* D);
 
+    template <std::derived_from<Decl> DeclTy>
+    void
+    populate(SourceInfo& I, DeclTy const* D);
+
+    /*  Parse the comments above a declaration as Javadoc
+
+        This function will parse the comments above a declaration
+        as Javadoc, and store the results in the `javadoc` input
+        parameter.
+
+        @return true if the comments were successfully parsed as
+        Javadoc, and false otherwise.
+     */
+    bool
+    populate(
+        std::optional<Javadoc>& javadoc,
+        Decl const* D);
+
     void
     populate(SourceInfo& I, clang::SourceLocation loc, bool definition, bool documented);
 
@@ -503,6 +521,9 @@ class ASTVisitor
     void
     populate(RecordInfo& I, ClassTemplateSpecializationDecl const* D);
 
+    void
+    populate(RecordInfo& I, ClassTemplatePartialSpecializationDecl const* D);
+
     void
     populate(FunctionInfo& I, FunctionDecl const* D);
 
@@ -548,6 +569,9 @@ class ASTVisitor
     void
     populate(VariableInfo& I, VarTemplateSpecializationDecl const* D);
 
+    void
+    populate(VariableInfo& I, VarTemplatePartialSpecializationDecl const* D);
+
     void
     populate(FieldInfo& I, FieldDecl const* D);
 
@@ -718,20 +742,6 @@ class ASTVisitor
     void
     addMember(std::vector<SymbolID>& container, Info const& Member) const;
 
-    /*  Parse the comments above a declaration as Javadoc
-
-        This function will parse the comments above a declaration
-        as Javadoc, and store the results in the `javadoc` input
-        parameter.
-
-        @return true if the comments were successfully parsed as
-        Javadoc, and false otherwise.
-     */
-    bool
-    generateJavadoc(
-        std::optional<Javadoc>& javadoc,
-        Decl const* D);
-
     Polymorphic<TypeInfo>
     toTypeInfo(QualType qt, TraversalMode mode);
 

src/lib/Gen/hbs/Builder.cpp

@@ -202,7 +202,7 @@ Builder(
                 return nullptr;
             }
             dom::Value decls = sourceInfo.get("decl");
-            if(dom::Value def = sourceInfo.get("def"))
+            if (dom::Value def = sourceInfo.get("def"))
             {
                 // for classes/enums, prefer the definition
                 if (dom::Value const kind = v.get("kind");
@@ -423,7 +423,7 @@ commonTemplatesDir() const
 
 std::string
 Builder::
-commonTemplatesDir(std::string_view subdir) const
+commonTemplatesDir(std::string_view const subdir) const
 {
     Config const& config = domCorpus->config;
     return files::appendPath(

src/lib/Lib/CorpusImpl.cpp

@@ -221,22 +221,22 @@ isTransparent(Info const& info)
 }
 }
 
-Info const*
+Expected<Info const*>
 CorpusImpl::
-lookup(SymbolID const& context, std::string_view name) const
+lookup(SymbolID const& context, std::string_view const name) const
 {
     return lookupImpl(*this, context, name);
 }
 
-Info const*
+Expected<Info const*>
 CorpusImpl::
 lookup(SymbolID const& context, std::string_view name)
 {
     return lookupImpl(*this, context, name);
 }
 
 template <class Self>
-Info const*
+Expected<Info const*>
 CorpusImpl::
 lookupImpl(Self&& self, SymbolID const& context, std::string_view name)
 {
@@ -246,16 +246,33 @@ lookupImpl(Self&& self, SymbolID const& context, std::string_view name)
     }
     if (auto [info, found] = self.lookupCacheGet(context, name); found)
     {
+        if (!info)
+        {
+            return Unexpected(formatError(
+                "Failed to find '{}' from context '{}'",
+                name,
+                self.Corpus::qualifiedName(*self.find(context))));
+        }
         return info;
     }
     Expected<ParsedRef> const s = parseRef(name);
     if (!s)
     {
-        report::warn("Failed to parse '{}'\n     {}", name, s.error().reason());
-        self.lookupCacheSet(context, name, nullptr);
-        return nullptr;
+        return Unexpected(formatError("Failed to parse '{}'\n     {}", name, s.error().reason()));
     }
     Info const* res = lookupImpl(self, context, *s, name, false);
+    if (!res)
+    {
+        auto const contextPtr = self.find(context);
+        if (!contextPtr)
+        {
+            return Unexpected(formatError("Failed to find '{}'", context));
+        }
+        return Unexpected(formatError(
+            "Failed to find '{}' from context '{}'",
+            name,
+            self.Corpus::qualifiedName(*contextPtr)));
+    }
     return res;
 }
 
@@ -600,7 +617,6 @@ CorpusImpl::finalize()
     report::debug("Finalizing javadoc");
     JavadocFinalizer finalizer(*this);
     finalizer.build();
-    finalizer.emitWarnings();
 }
 
 

src/lib/Lib/CorpusImpl.hpp

@@ -91,10 +91,10 @@ class CorpusImpl final : public Corpus
     Info const*
     find(SymbolID const& id) const noexcept override;
 
-    Info const*
+    Expected<Info const*>
     lookup(SymbolID const& context, std::string_view name) const override;
 
-    Info const*
+    Expected<Info const*>
     lookup(SymbolID const& context, std::string_view name);
 
     /** Build metadata for a set of translation units.
@@ -141,7 +141,7 @@ class CorpusImpl final : public Corpus
 
     template <class Self>
     static
-    Info const*
+    Expected<Info const*>
     lookupImpl(
         Self&& self,
         SymbolID const& context,