diff --git a/docs/mrdocs.schema.json b/docs/mrdocs.schema.json index 7cd8a8efa..50001dab6 100644 --- a/docs/mrdocs.schema.json +++ b/docs/mrdocs.schema.json @@ -17,6 +17,16 @@ "title": "Use the first line of the comment as the brief", "type": "boolean" }, + "auto-function-metadata": { + "default": true, + "description": "When set to `true`, MrDocs automatically provides documentation for special functions, such as constructors, destructors, and operators. It also provides documentation for missing documentation metadata, such as known types.", + "enum": [ + true, + false + ], + "title": "Automatically provide missing documentation for special functions and trivial metadata", + "type": "boolean" + }, "auto-relates": { "default": true, "description": "When set to `true`, MrDocs automatically finds non-member functions that are related to the current class.", diff --git a/include/mrdocs/Metadata/Info/Function.hpp b/include/mrdocs/Metadata/Info/Function.hpp index 56489b23e..4a41a5ef3 100644 --- a/include/mrdocs/Metadata/Info/Function.hpp +++ b/include/mrdocs/Metadata/Info/Function.hpp @@ -70,6 +70,13 @@ getSafeOperatorName( OperatorKind kind, bool include_keyword = false) noexcept; +/** Return the human-readable name of the operator + */ +std::optional +getOperatorReadableName( + OperatorKind kind, + int nParams); + /** Function classifications */ enum class FunctionClass { diff --git a/include/mrdocs/Metadata/Javadoc.hpp b/include/mrdocs/Metadata/Javadoc.hpp index 5fd277f40..eb61c9d2a 100644 --- a/include/mrdocs/Metadata/Javadoc.hpp +++ b/include/mrdocs/Metadata/Javadoc.hpp @@ -119,7 +119,7 @@ enum class NodeKind styled, tparam, reference, - copied, + copy_details, throws, details, see, @@ -373,7 +373,8 @@ struct Text : Node { } - bool isBlock() const noexcept final + bool + isBlock() const noexcept final { return false; } @@ -600,26 +601,21 @@ tag_invoke( /** Documentation copied from another symbol. */ -struct Copied final : Reference +struct CopyDetails final : Reference { - Parts parts; + static constexpr auto static_kind = NodeKind::copy_details; - static constexpr auto static_kind = NodeKind::copied; - - Copied( - std::string string_ = std::string(), - Parts parts_ = Parts::all) noexcept - : Reference(std::move(string_), NodeKind::copied) - , parts(parts_) + CopyDetails(std::string string_ = std::string()) noexcept + : Reference(std::move(string_), NodeKind::copy_details) { } - auto operator<=>(Copied const&) const = default; - bool operator==(Copied const&) const noexcept = default; + auto operator<=>(CopyDetails const&) const = default; + bool operator==(CopyDetails const&) const noexcept = default; bool equals(Node const& other) const noexcept override { return Kind == other.Kind && - *this == dynamic_cast(other); + *this == dynamic_cast(other); } }; @@ -630,11 +626,10 @@ void tag_invoke( dom::LazyObjectMapTag t, IO& io, - Copied const& I, + CopyDetails const& I, DomCorpus const* domCorpus) { tag_invoke(t, io, dynamic_cast(I), domCorpus); - io.map("parts", I.parts); } /** Return the @ref Copied as a @ref dom::Value object. @@ -644,7 +639,7 @@ void tag_invoke( dom::ValueFromTag, dom::Value& v, - Copied const& I, + CopyDetails const& I, DomCorpus const* domCorpus) { v = dom::LazyObject(I, domCorpus); @@ -825,10 +820,11 @@ struct Paragraph : Block { static constexpr auto static_kind = NodeKind::paragraph; - Paragraph() noexcept - : Block(NodeKind::paragraph) - { - } + Paragraph() noexcept : Block(NodeKind::paragraph) {} + + virtual + Paragraph& + operator=(std::string_view str); auto operator<=>(Paragraph const&) const = default; @@ -881,11 +877,30 @@ struct Brief final : Paragraph { static constexpr NodeKind static_kind = NodeKind::brief; + std::vector copiedFrom; + Brief() noexcept : Paragraph(NodeKind::brief) { } + explicit + Brief(std::string_view const text) + : Brief() + { + operator=(text); + } + + Brief& + operator=(Brief const& other) = default; + + Brief& + operator=(std::string_view const text) override + { + Paragraph::operator=(text); + return *this; + } + auto operator<=>(Brief const&) const = default; bool equals(Node const& other) const noexcept override @@ -939,8 +954,12 @@ struct Admonition final : Paragraph { } + using Paragraph::operator=; + auto operator<=>(Admonition const&) const = default; + bool operator==(Admonition const&) const noexcept = default; + bool equals(Node const& other) const noexcept override { return Kind == other.Kind && @@ -989,6 +1008,7 @@ struct Code final : Paragraph { } + using Paragraph::operator=; auto operator<=>(Code const&) const = default; bool operator==(Code const&) const noexcept = default; bool equals(Node const& other) const noexcept override @@ -1034,6 +1054,8 @@ struct ListItem final : Paragraph : Paragraph(static_kind) {} + using Paragraph::operator=; + auto operator<=>(ListItem const&) const = default; bool operator==(ListItem const&) const noexcept = default; @@ -1093,6 +1115,8 @@ struct UnorderedList final : Paragraph { } + using Paragraph::operator=; + auto operator<=>(UnorderedList const& other) const { if (auto const cmp = items.size() <=> other.items.size(); !std::is_eq(cmp)) @@ -1169,6 +1193,8 @@ struct See final : Paragraph { } + using Paragraph::operator=; + auto operator<=>(See const&) const = default; bool operator==(See const&) @@ -1228,6 +1254,30 @@ struct Param final : Paragraph { } + explicit + Param( + std::string_view const name, + std::string_view const text) + : Param() + { + this->name = name; + this->operator=(text); + } + + explicit + Param(Paragraph const& other) + : Param() + { + children = other.children; + } + + Param& + operator=(std::string_view const text) override + { + Paragraph::operator=(text); + return *this; + } + auto operator<=>(Param const&) const = default; bool operator==(Param const&) @@ -1279,6 +1329,27 @@ struct Returns final : Paragraph { } + explicit + Returns(std::string_view const text) + : Returns() + { + operator=(text); + } + + explicit + Returns(Paragraph const& other) + : Returns() + { + children = other.children; + } + + Returns& + operator=(std::string_view const text) override + { + Paragraph::operator=(text); + return *this; + } + auto operator<=>(Returns const&) const = default; bool operator==(Returns const&) @@ -1330,6 +1401,8 @@ struct TParam final : Paragraph { } + using Paragraph::operator=; + auto operator<=>(TParam const&) const = default; bool operator==(TParam const&) const noexcept = default; bool equals(Node const& other) const noexcept override @@ -1384,6 +1457,8 @@ struct Throws final : Paragraph { } + using Paragraph::operator=; + auto operator<=>(Throws const&) const = default; bool operator==(Throws const&) @@ -1435,6 +1510,8 @@ struct Precondition final : Paragraph { } + using Paragraph::operator=; + auto operator<=>(Precondition const&) const = default; bool operator==(Precondition const&) @@ -1485,6 +1562,8 @@ struct Postcondition : Paragraph { } + using Paragraph::operator=; + auto operator<=>(Postcondition const&) const = default; bool operator==(Postcondition const&) @@ -1561,8 +1640,8 @@ visit( return visitor.template visit(); case NodeKind::reference: return visitor.template visit(); - case NodeKind::copied: - return visitor.template visit(); + case NodeKind::copy_details: + return visitor.template visit(); case NodeKind::list_item: return visitor.template visit(); case NodeKind::unordered_list: @@ -1698,14 +1777,6 @@ struct MRDOCS_DECL postconditions.empty(); } - /** Return the brief, or nullptr if there is none. - */ - doc::Paragraph const* - getBrief(Corpus const& corpus) const noexcept; - - std::vector> const& - getDescription(Corpus const& corpus) const noexcept; - /** Return the list of top level blocks. */ std::vector> const& diff --git a/include/mrdocs/Metadata/Specifiers.hpp b/include/mrdocs/Metadata/Specifiers.hpp index b9d069da4..11c00e210 100644 --- a/include/mrdocs/Metadata/Specifiers.hpp +++ b/include/mrdocs/Metadata/Specifiers.hpp @@ -180,6 +180,18 @@ tag_invoke( v = static_cast>(kind); } +/** Determines whether the operator is potentially unary. + */ +MRDOCS_DECL +bool +isUnaryOperator(OperatorKind kind) noexcept; + +/** Determines whether the operator is potentially binary. + */ +MRDOCS_DECL +bool +isBinaryOperator(OperatorKind kind) noexcept; + /** Reference type kinds */ enum class ReferenceKind diff --git a/include/mrdocs/Support/Algorithm.hpp b/include/mrdocs/Support/Algorithm.hpp index ee8b31651..9bc8a1218 100644 --- a/include/mrdocs/Support/Algorithm.hpp +++ b/include/mrdocs/Support/Algorithm.hpp @@ -25,7 +25,7 @@ namespace clang::mrdocs { template requires std::equality_comparable_with> bool -contains(Range const& range, El const& el) +contains(Range&& range, El const& el) { return std::find( std::ranges::begin(range), diff --git a/src/lib/AST/ParseJavadoc.cpp b/src/lib/AST/ParseJavadoc.cpp index 3f52c7d54..a12346a1e 100644 --- a/src/lib/AST/ParseJavadoc.cpp +++ b/src/lib/AST/ParseJavadoc.cpp @@ -992,10 +992,30 @@ visitInlineCommandComment( std::string ref = C->getArgText(0).str(); std::string leftOver = fixReference(ref); bool const hasExtra = !leftOver.empty(); - emplaceText( - C->hasTrailingNewline() && !hasExtra, - ref, - convertCopydoc(ID)); + doc::Parts const parts = convertCopydoc(ID); + bool const copyBrief = parts == doc::Parts::brief || parts == doc::Parts::all; + bool const copyDetails = parts == doc::Parts::description || parts == doc::Parts::all; + MRDOCS_ASSERT(copyBrief || copyDetails); + if (copyBrief) + { + // The brief is metadata associated with the javadoc + if (!jd_.brief) + { + jd_.brief.emplace(); + } + if (!contains(jd_.brief->copiedFrom, ref)) + { + jd_.brief->copiedFrom.emplace_back(ref); + } + } + if (copyDetails) + { + // The details are in the main body of the javadoc + // and are replaced at the same position as the command + emplaceText( + C->hasTrailingNewline() && !hasExtra, + ref); + } if (hasExtra) { emplaceText( diff --git a/src/lib/AST/ParseRef.cpp b/src/lib/AST/ParseRef.cpp index 6a279bb78..6209f011c 100644 --- a/src/lib/AST/ParseRef.cpp +++ b/src/lib/AST/ParseRef.cpp @@ -854,9 +854,9 @@ class RefParser bool parseDeclarationSpecifiers(Polymorphic& dest) { - static constexpr std::string_view typeQualifiers[] = { - "const", "volatile" - }; + //static constexpr std::string_view typeQualifiers[] = { + // "const", "volatile" + //}; static constexpr std::string_view typeModifiers[] = { "long", "short", "signed", "unsigned" }; diff --git a/src/lib/Gen/xml/XMLWriter.cpp b/src/lib/Gen/xml/XMLWriter.cpp index df3b7c9e1..69d0222ad 100644 --- a/src/lib/Gen/xml/XMLWriter.cpp +++ b/src/lib/Gen/xml/XMLWriter.cpp @@ -797,8 +797,8 @@ writeNode(doc::Node const& node) case doc::NodeKind::reference: writeReference(dynamic_cast(node)); break; - case doc::NodeKind::copied: - writeCopied(dynamic_cast(node)); + case doc::NodeKind::copy_details: + writeCopied(dynamic_cast(node)); break; case doc::NodeKind::throws: writeThrows(dynamic_cast(node)); @@ -831,23 +831,9 @@ writeReference( void XMLWriter:: writeCopied( - doc::Copied const& node) + doc::CopyDetails const& node) { - std::string_view tag_name; - switch(node.parts) - { - case doc::Parts::all: - tag_name = "copydoc"; - break; - case doc::Parts::brief: - tag_name = "copybrief"; - break; - case doc::Parts::description: - tag_name = "copydetails"; - break; - default: - MRDOCS_UNREACHABLE(); - } + std::string_view const tag_name = "copydetails"; tags_.write(tag_name, node.string, { { node.id } }); diff --git a/src/lib/Gen/xml/XMLWriter.hpp b/src/lib/Gen/xml/XMLWriter.hpp index 28bd07feb..65ac72e5b 100644 --- a/src/lib/Gen/xml/XMLWriter.hpp +++ b/src/lib/Gen/xml/XMLWriter.hpp @@ -88,7 +88,7 @@ class XMLWriter void writeText(doc::Text const& node); void writeTParam(doc::TParam const& node); void writeReference(doc::Reference const& node); - void writeCopied(doc::Copied const& node); + void writeCopied(doc::CopyDetails const& node); void writeThrows(doc::Throws const& node); void writeSee(doc::See const& node, llvm::StringRef tag = ""); void writePrecondition(doc::Precondition const& node); diff --git a/src/lib/Lib/ConfigOptions.json b/src/lib/Lib/ConfigOptions.json index ea02e4f04..da5951c24 100644 --- a/src/lib/Lib/ConfigOptions.json +++ b/src/lib/Lib/ConfigOptions.json @@ -177,6 +177,13 @@ "details": "When set to `true`, MrDocs automatically finds non-member functions that are related to the current class.", "type": "bool", "default": true + }, + { + "name": "auto-function-metadata", + "brief": "Automatically provide missing documentation for special functions and trivial metadata", + "details": "When set to `true`, MrDocs automatically provides documentation for special functions, such as constructors, destructors, and operators. It also provides documentation for missing documentation metadata, such as known types.", + "type": "bool", + "default": true } ] }, diff --git a/src/lib/Metadata/Finalizers/Javadoc/Function.hpp b/src/lib/Metadata/Finalizers/Javadoc/Function.hpp new file mode 100644 index 000000000..1560ae0d5 --- /dev/null +++ b/src/lib/Metadata/Finalizers/Javadoc/Function.hpp @@ -0,0 +1,778 @@ +// +// Licensed under the Apache License v2.0 with LLVM Exceptions. +// See https://llvm.org/LICENSE.txt for license information. +// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception +// +// Copyright (c) 2025 Alan de Freitas (alandefreitas@gmail.com) +// +// Official repository: https://github.com/cppalliance/mrdocs +// + +#ifndef MRDOCS_LIB_METADATA_FINALIZER_JAVADOCFINALIZER_FUNCTION_HPP +#define MRDOCS_LIB_METADATA_FINALIZER_JAVADOCFINALIZER_FUNCTION_HPP + +#include "lib/Lib/CorpusImpl.hpp" +#include "lib/Lib/Info.hpp" +#include +#include + +namespace clang::mrdocs { +namespace { +bool +isSpecialFunction(FunctionInfo const& I) +{ + return + I.Class != FunctionClass::Normal || + I.OverloadedOperator != OperatorKind::None; +} + +bool +isDefaultConstructor(FunctionInfo const& I) +{ + return I.Class == FunctionClass::Constructor && I.Params.empty(); +} + +template +bool +isCopyOrMoveConstructorOrAssignment(FunctionInfo const& I) +{ + if constexpr (!assignment) + { + MRDOCS_CHECK_OR(I.Class == FunctionClass::Constructor, false); + } + else + { + MRDOCS_CHECK_OR(I.OverloadedOperator == OperatorKind::Equal, false); + } + MRDOCS_CHECK_OR(I.Params.size() == 1, false); + auto const& param = I.Params[0]; + auto const& paramType = param.Type; + MRDOCS_CHECK_OR(paramType, false); + if constexpr (!move) + { + MRDOCS_CHECK_OR(paramType->isLValueReference(), false); + } + else + { + MRDOCS_CHECK_OR(paramType->isRValueReference(), false); + } + using RefType = std::conditional_t; + auto const& paramRefType = get(paramType); + auto const& paramRefPointee = paramRefType.PointeeType; + MRDOCS_CHECK_OR(paramRefPointee, false); + auto const& paramRefPointeeNamed = get(paramRefPointee); + MRDOCS_CHECK_OR(paramRefPointeeNamed.Name, false); + auto const& paramName = paramRefPointeeNamed.Name; + MRDOCS_CHECK_OR(paramName, false); + auto const& paramRefPointeeNamedName = paramName->Name; + MRDOCS_CHECK_OR(!paramRefPointeeNamedName.empty(), false); + SymbolID const& id = paramName->id; + MRDOCS_CHECK_OR(id, false); + return id == I.Parent; +} + +bool +isCopyConstructor(FunctionInfo const& I) +{ + return isCopyOrMoveConstructorOrAssignment(I); +} + +bool +isMoveConstructor(FunctionInfo const& I) +{ + return isCopyOrMoveConstructorOrAssignment(I); +} + +bool +isCopyAssignment(FunctionInfo const& I) +{ + return isCopyOrMoveConstructorOrAssignment(I); +} + +bool +isMoveAssignment(FunctionInfo const& I) +{ + return isCopyOrMoveConstructorOrAssignment(I); +} + +std::optional +innermostTypenameString(Polymorphic const& T) +{ + auto& R = innermostType(T); + MRDOCS_CHECK_OR(R->isNamed(), nullptr); + MRDOCS_CHECK_OR(get(R).Name, nullptr); + MRDOCS_CHECK_OR(!get(R).Name->Name.empty(), nullptr); + auto& RStr = get(R).Name->Name; + return RStr; +} + +bool +populateFunctionBriefFromClass(FunctionInfo& I, CorpusImpl const& corpus) +{ + switch (I.Class) + { + case FunctionClass::Normal: + return false; + case FunctionClass::Constructor: + { + if (isDefaultConstructor(I)) + { + I.javadoc->brief = "Default constructor"; + return true; + } + if (isCopyConstructor(I)) + { + I.javadoc->brief = "Copy constructor"; + return true; + } + if (isMoveConstructor(I)) + { + I.javadoc->brief = "Move constructor"; + return true; + } + if (I.Params.size() == 1) + { + auto const& param = I.Params[0]; + if (auto const res = innermostTypenameString(param.Type)) + { + if (!I.javadoc->brief) + { + I.javadoc->brief.emplace(); + } + I.javadoc->brief->children.clear(); + I.javadoc->brief->children.emplace_back( + MakePolymorphic(std::string("Construct from "))); + I.javadoc->brief->children.emplace_back( + MakePolymorphic( + std::string(*res), + doc::Style::mono)); + return true; + } + } + I.javadoc->brief = "Constructor"; + return true; + } + case FunctionClass::Destructor: + { + I.javadoc->brief = "Destructor"; + return true; + } + case FunctionClass::Conversion: + { + if (auto const R = innermostTypenameString(I.ReturnType)) + { + auto const RStr = *R; + I.javadoc->brief.emplace(); + I.javadoc->brief->children.emplace_back( + MakePolymorphic(std::string("Conversion to "))); + I.javadoc->brief->children.emplace_back( + MakePolymorphic( + std::string(RStr), + doc::Style::mono)); + } + else + { + I.javadoc->brief = "Conversion operator"; + } + return true; + } + default: + MRDOCS_UNREACHABLE(); + } +} + +bool +isStreamInsertion(FunctionInfo const& function) +{ + MRDOCS_CHECK_OR(!function.IsRecordMethod, false); + MRDOCS_CHECK_OR(function.Params.size() == 2, false); + MRDOCS_CHECK_OR(function.OverloadedOperator == OperatorKind::LessLess, false); + // Check first param is mutable left reference + auto& firstParam = function.Params[0]; + MRDOCS_CHECK_OR(firstParam, false); + auto& firstQualType = firstParam.Type; + MRDOCS_CHECK_OR(firstQualType, false); + MRDOCS_CHECK_OR(firstQualType->isLValueReference(), false); + auto& firstNamedType = get(firstQualType).PointeeType; + MRDOCS_CHECK_OR(firstNamedType, false); + MRDOCS_CHECK_OR(firstNamedType->isNamed(), false); + // Check return type + return firstQualType == function.ReturnType; +} + +bool +populateFunctionBriefFromOperator(FunctionInfo& I) +{ + MRDOCS_CHECK_OR(I.OverloadedOperator != OperatorKind::None, false); + + // Stream insertion operators are implemented as an exception to the operator name + if (isStreamInsertion(I)) + { + I.javadoc->brief = "Stream insertion operator"; + return true; + } + + if (isCopyAssignment(I)) + { + I.javadoc->brief = "Copy assignment operator"; + return true; + } + + if (isMoveAssignment(I)) + { + I.javadoc->brief = "Move assignment operator"; + return true; + } + + // Find the operator name + auto const res = + getOperatorReadableName( + I.OverloadedOperator, + I.Params.size() + I.IsRecordMethod); + MRDOCS_CHECK_OR(res, false); + std::string briefStr(*res); + briefStr += " operator"; + I.javadoc->brief = std::move(briefStr); + return true; +} + +void +populateFunctionBrief(FunctionInfo& I, CorpusImpl const& corpus) +{ + MRDOCS_CHECK_OR(!I.javadoc->brief); + MRDOCS_CHECK_OR(!populateFunctionBriefFromClass(I, corpus)); + MRDOCS_CHECK_OR(!populateFunctionBriefFromOperator(I)); +} + + + + +Info const* +getInfo( + Polymorphic const& R, + CorpusImpl const& corpus) +{ + SymbolID const id = R->namedSymbol(); + MRDOCS_CHECK_OR(id, nullptr); + Info const* Rinfo = corpus.find(id); + return Rinfo; +} + +doc::Brief const* +getInfoBrief( + Polymorphic const& R, + CorpusImpl const& corpus) +{ + Info const* Rinfo = getInfo(R, corpus); + MRDOCS_CHECK_OR(Rinfo, nullptr); + MRDOCS_CHECK_OR(Rinfo->javadoc, nullptr); + MRDOCS_CHECK_OR(Rinfo->javadoc->brief, nullptr); + return &*Rinfo->javadoc->brief; +} + +bool +populateFunctionReturnsFromFunctionBrief( + FunctionInfo& I) +{ + MRDOCS_CHECK_OR(I.javadoc->brief, false); + MRDOCS_CHECK_OR(I.javadoc->brief->children.size() == 1, false); + auto& brief = I.javadoc->brief->children[0]; + MRDOCS_CHECK_OR(brief->Kind == doc::NodeKind::text, false); + std::string_view briefText = brief->string; + static constexpr std::string_view briefPrefixes[] = { + "Returns ", + "Return ", + "Get ", + "Gets ", + "Determine ", + "Determines ", + }; + for (std::string_view prefix: briefPrefixes) + { + if (briefText.starts_with(prefix)) + { + briefText.remove_prefix(prefix.size()); + I.javadoc->returns.emplace_back(std::string(briefText)); + return true; + } + } + return false; +} + + +bool +populateFunctionReturnsForSpecial( + FunctionInfo& I, + Polymorphic const& innerR, + CorpusImpl const& corpus) +{ + if (I.Class == FunctionClass::Conversion) + { + if (auto* brief = getInfoBrief(innerR, corpus)) + { + I.javadoc->returns.emplace_back(*brief); + return true; + } + auto const exp = innermostTypenameString(innerR); + MRDOCS_CHECK_OR(exp, false); + doc::Returns r; + r.children.emplace_back(MakePolymorphic(std::string("The object converted to "))); + r.children.emplace_back(MakePolymorphic( + std::string(*exp), + doc::Style::mono)); + I.javadoc->returns.emplace_back(std::move(r)); + return true; + } + MRDOCS_CHECK_OR(I.OverloadedOperator != OperatorKind::None, false); + + // Stream operator + if (isStreamInsertion(I)) + { + I.javadoc->returns.emplace_back("Reference to the current output stream"); + return true; + } + + // Special functions that should return a reference to self + if (I.ReturnType->isLValueReference()) + { + Info const* RInfo = getInfo(innerR, corpus); + MRDOCS_CHECK_OR(RInfo, false); + MRDOCS_CHECK_OR(RInfo->id == I.Parent, false); + I.javadoc->returns.emplace_back("Reference to the current object"); + return true; + } + + // Special functions that should return a pointer to self + if (I.ReturnType->isPointer()) + { + Info const* RInfo = getInfo(innerR, corpus); + MRDOCS_CHECK_OR(RInfo, false); + MRDOCS_CHECK_OR(RInfo->id == I.Parent, false); + I.javadoc->returns.emplace_back("Pointer to the current object"); + return true; + } + + // Special functions that can return bool + if (is_one_of( + I.OverloadedOperator, + { OperatorKind::EqualEqual, + OperatorKind::ExclaimEqual, + OperatorKind::Less, + OperatorKind::LessEqual, + OperatorKind::Greater, + OperatorKind::GreaterEqual, + OperatorKind::Exclaim })) + { + MRDOCS_CHECK_OR(I.ReturnType->isNamed(), false); + MRDOCS_CHECK_OR( + get(I.ReturnType).FundamentalType + == FundamentalTypeKind::Bool, + false); + doc::Returns r; + r.children.emplace_back(MakePolymorphic( + std::string("true"), + doc::Style::mono)); + std::string_view midText; + switch (I.OverloadedOperator) + { + case OperatorKind::EqualEqual: + midText = " if the objects are equal, "; + break; + case OperatorKind::ExclaimEqual: + midText = " if the objects are not equal, "; + break; + case OperatorKind::Less: + midText = " if the left object is less than the right object, "; + break; + case OperatorKind::LessEqual: + midText = " if the left object is less than or equal to the right object, "; + break; + case OperatorKind::Greater: + midText = " if the left object is greater than the right object, "; + break; + case OperatorKind::GreaterEqual: + midText = " if the left object is greater than or equal to the right object, "; + break; + case OperatorKind::Exclaim: + midText = " if the object is falsy, "; + break; + default: + MRDOCS_UNREACHABLE(); + } + r.children.emplace_back(MakePolymorphic(std::string(midText))); + r.children.emplace_back(MakePolymorphic( + std::string("false"), + doc::Style::mono)); + r.children.emplace_back(MakePolymorphic(std::string(" otherwise"))); + I.javadoc->returns.emplace_back(std::move(r)); + return false; + } + + // Spaceship operator + if (I.OverloadedOperator == OperatorKind::Spaceship) + { + I.javadoc->returns.emplace_back("The relative order of the objects"); + return true; + } + + // Special function that return the same type as the parent + if (I.IsRecordMethod && + innerR->isNamed() && + get(innerR).Name && + get(innerR).Name->id && + get(innerR).Name->id == I.Parent) + { + if (I.ReturnType->isLValueReference()) + { + I.javadoc->returns.emplace_back("Reference to the current object"); + } + else if (I.ReturnType->isRValueReference()) + { + I.javadoc->returns.emplace_back("Rvalue reference to the current object"); + } + else if (I.ReturnType->isPointer()) + { + I.javadoc->returns.emplace_back("Pointer to the current object"); + } + else + { + I.javadoc->returns.emplace_back("Another instance of the object"); + } + return true; + } + + return false; +} + +bool +populateFunctionReturnsFromReturnTypeBrief( + FunctionInfo& I, + Polymorphic const& innerR, + CorpusImpl const& corpus) +{ + if (auto* brief = getInfoBrief(innerR, corpus)) + { + I.javadoc->returns.emplace_back(*brief); + return true; + } + return false; +} + +void +populateFunctionReturns(FunctionInfo& I, CorpusImpl const& corpus) +{ + MRDOCS_CHECK_OR(I.javadoc->returns.empty()); + + // Populate the return doc from brief of the function + // when the brief is "Returns ..." + MRDOCS_CHECK_OR(!populateFunctionReturnsFromFunctionBrief(I)); + + // Check if we have a named return type + MRDOCS_CHECK_OR(I.ReturnType); + auto& inner = innermostType(I.ReturnType); + MRDOCS_CHECK_OR(inner); + if (inner->isNamed()) + { + auto& Ninner = get(inner); + MRDOCS_CHECK_OR(Ninner.Name); + MRDOCS_CHECK_OR(!Ninner.Name->Name.empty()); + MRDOCS_CHECK_OR(Ninner.FundamentalType != FundamentalTypeKind::Void); + } + + // If we have a named return type, we can populate the returns + // Populate the return doc for special functions + MRDOCS_CHECK_OR(!populateFunctionReturnsForSpecial(I, inner, corpus)); + + // Populate the return doc from the return type brief + MRDOCS_CHECK_OR(!populateFunctionReturnsFromReturnTypeBrief(I, inner, corpus)); +} + +/* Get a list of all parameter names in javadoc + + The javadoc parameter names can contain a single parameter or + a list of parameters separated by commas. This function + returns a list of all parameter names in the javadoc. + */ +SmallVector +getJavadocParamNames(Javadoc const& javadoc) +{ + SmallVector result; + for (auto const& javadocParam: javadoc.params) + { + auto const& paramNamesStr = javadocParam.name; + for (auto paramNames = std::views::split(paramNamesStr, ','); + auto const& paramName: paramNames) + { + result.push_back(trim(std::string_view(paramName.begin(), paramName.end()))); + } + } + return result; +} + +bool +setCntrOrAssignParamName( + FunctionInfo& I, + Param& param, + std::size_t const index) +{ + MRDOCS_CHECK_OR(index == 0, false); + MRDOCS_CHECK_OR(I.Params.size() == 1, false); + MRDOCS_CHECK_OR(I.IsRecordMethod, false); + MRDOCS_CHECK_OR( + I.Class == FunctionClass::Constructor || + I.OverloadedOperator == OperatorKind::Equal, + false); + auto paramNames = std::views:: + transform(I.Params, [](Param const& p) -> std::string_view { + return *p.Name; + }); + auto& innerP = innermostType(param.Type); + std::string_view paramName = "value"; + if (innerP->namedSymbol() == I.Parent) + { + paramName = "other"; + } + MRDOCS_CHECK_OR(!contains(paramNames, paramName), false); + param.Name = paramName; + return true; +} + +bool +setStreamOperatorParamName( + FunctionInfo& I, + Param& param, + std::size_t const index) +{ + MRDOCS_CHECK_OR(index < 2, false); + MRDOCS_CHECK_OR(isStreamInsertion(I), false); + auto paramNames = std::views:: + transform(I.Params, [](Param const& p) -> std::string_view { + return *p.Name; + }); + std::string_view paramName = + index == 0 ? "os" : "value"; + MRDOCS_CHECK_OR(!contains(paramNames, paramName), false); + param.Name = paramName; + return true; +} + +bool +setBinaryOpParamName( + FunctionInfo& I, + Param& param, + std::size_t const index) +{ + MRDOCS_CHECK_OR((I.IsRecordMethod && index == 0) || index < 2, false); + MRDOCS_CHECK_OR(isBinaryOperator(I.OverloadedOperator), false); + std::size_t const sizeFree = I.IsRecordMethod ? I.Params.size() + 1 : I.Params.size(); + MRDOCS_CHECK_OR(sizeFree == 2, false); + + auto const paramNames = std::views:: + transform(I.Params, [](Param const& p) -> std::string_view { + return *p.Name; + }); + std::size_t const indexFree = I.IsRecordMethod ? index + 1 : index; + std::string_view paramName = indexFree == 0 ? "lhs" : "rhs"; + MRDOCS_CHECK_OR(!contains(paramNames, paramName), false); + param.Name = paramName; + return true; +} + +bool +setUnaryOpParamName( + FunctionInfo& I, + Param& param, + std::size_t const index) +{ + MRDOCS_CHECK_OR(!I.IsRecordMethod, false); + MRDOCS_CHECK_OR(index == 0, false); + MRDOCS_CHECK_OR(isUnaryOperator(I.OverloadedOperator), false); + MRDOCS_CHECK_OR(I.Params.size() == 1, false); + + auto const paramNames = std::views:: + transform(I.Params, [](Param const& p) -> std::string_view { + return *p.Name; + }); + std::string_view paramName = "value"; + MRDOCS_CHECK_OR(!contains(paramNames, paramName), false); + param.Name = paramName; + return true; +} + +bool +setSpecialFunctionParamName( + FunctionInfo& I, + Param& param, + std::size_t index) +{ + MRDOCS_CHECK_OR(!setCntrOrAssignParamName(I, param, index), true); + MRDOCS_CHECK_OR(!setStreamOperatorParamName(I, param, index), true); + MRDOCS_CHECK_OR(!setBinaryOpParamName(I, param, index), true); + MRDOCS_CHECK_OR(!setUnaryOpParamName(I, param, index), true); + return false; +} + +bool +setCntrOrAssignParamDoc( + FunctionInfo& I, + Param& param, + std::size_t const index) +{ + MRDOCS_CHECK_OR(index == 0, false); + MRDOCS_CHECK_OR(I.IsRecordMethod, false); + MRDOCS_CHECK_OR( + I.Class == FunctionClass::Constructor || + I.OverloadedOperator == OperatorKind::Equal, + false); + + // Set the parameter description if we can + MRDOCS_CHECK_OR(param, false); + auto& innerParam = innermostType(param.Type); + MRDOCS_CHECK_OR(innerParam, false); + MRDOCS_CHECK_OR(innerParam->isNamed(), false); + std::string_view const paramNoun + = get(innerParam).FundamentalType ? + "value" : + "object"; + std::string_view const functionVerb = [&]() { + bool const isAssign = I.OverloadedOperator == OperatorKind::Equal; + if (get(innerParam).FundamentalType) + { + return !isAssign ? "construct" : "assign"; + } + if (param.Type->isLValueReference()) + { + return !isAssign ? "copy construct" : "copy assign"; + } + if (param.Type->isRValueReference()) + { + return !isAssign ? "move construct" : "move assign"; + } + return !isAssign ? "construct" : "assign"; + }(); + I.javadoc->params.emplace_back(*param.Name, fmt::format( + "The {} to {} from", paramNoun, functionVerb)); + return true; +} + +bool +setBinaryOpParamDoc( + FunctionInfo& I, + Param& param, + std::size_t const index) +{ + std::size_t const indexFree = I.IsRecordMethod ? index + 1 : index; + std::size_t const sizeFree = I.IsRecordMethod ? I.Params.size() + 1 : I.Params.size(); + MRDOCS_CHECK_OR(indexFree < 2, false); + MRDOCS_CHECK_OR(isBinaryOperator(I.OverloadedOperator), false); + MRDOCS_CHECK_OR(sizeFree == 2, false); + + // Set the parameter description if we can + std::string_view const paramAdj = indexFree == 0 ? "left" : "right"; + I.javadoc->params.emplace_back(*param.Name, fmt::format( + "The {} operand", paramAdj)); + return true; +} + +bool +setUnaryOpParamDoc( + FunctionInfo& I, + Param& param, + std::size_t const index) +{ + MRDOCS_CHECK_OR(!I.IsRecordMethod, false); + MRDOCS_CHECK_OR(index == 0, false); + MRDOCS_CHECK_OR(isUnaryOperator(I.OverloadedOperator), false); + MRDOCS_CHECK_OR(I.Params.size() == 1, false); + + // Set the parameter description if we can + I.javadoc->params.emplace_back(*param.Name, "The operand"); + return true; +} + +bool +setStreamOperatorParamDoc( + FunctionInfo& I, + Param& param, + std::size_t const index) +{ + MRDOCS_CHECK_OR(index < 2, false); + MRDOCS_CHECK_OR(isStreamInsertion(I), false); + if (index == 0) + { + I.javadoc->params.emplace_back(*param.Name, "An output stream"); + } + else + { + I.javadoc->params.emplace_back(*param.Name, "The object to output"); + } + return true; +} + +void +setFunctionParamDoc( + FunctionInfo& I, + Param& param, + std::size_t const index, + CorpusImpl const& corpus) +{ + if (setCntrOrAssignParamDoc(I, param, index)) + { + return; + } + if (setStreamOperatorParamDoc(I, param, index)) + { + return; + } + if (setBinaryOpParamDoc(I, param, index)) + { + return; + } + + if (setUnaryOpParamDoc(I, param, index)) + { + return; + } + + // param is a named parameter: use the brief of the type + // as a description for the parameter + auto const& innerParam = innermostType(param.Type); + doc::Brief const* paramBrief = getInfoBrief(innerParam, corpus); + MRDOCS_CHECK_OR(paramBrief); + I.javadoc->params.emplace_back(*param.Name, *paramBrief); +} + +void +populateFunctionParam( + FunctionInfo& I, + Param& param, + std::size_t const index, + SmallVector& documentedParams, + CorpusImpl const& corpus) +{ + if (!param.Name) + { + setSpecialFunctionParamName( + I, + param, + index); + } + MRDOCS_CHECK_OR(param.Name); + MRDOCS_CHECK_OR(!contains(documentedParams, *param.Name)); + setFunctionParamDoc(I, param, index, corpus); +} + +void +populateFunctionParams(FunctionInfo& I, CorpusImpl const& corpus) +{ + auto documentedParams = getJavadocParamNames(*I.javadoc); + for (std::size_t i = 0; i < I.Params.size(); ++i) + { + populateFunctionParam(I, I.Params[i], i, documentedParams, corpus); + } +} + +} +} // clang::mrdocs + +#endif diff --git a/src/lib/Metadata/Finalizers/Javadoc/Overloads.hpp b/src/lib/Metadata/Finalizers/Javadoc/Overloads.hpp new file mode 100644 index 000000000..16fe6c10d --- /dev/null +++ b/src/lib/Metadata/Finalizers/Javadoc/Overloads.hpp @@ -0,0 +1,364 @@ +// +// Licensed under the Apache License v2.0 with LLVM Exceptions. +// See https://llvm.org/LICENSE.txt for license information. +// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception +// +// Copyright (c) 2025 Alan de Freitas (alandefreitas@gmail.com) +// +// Official repository: https://github.com/cppalliance/mrdocs +// + +#ifndef MRDOCS_LIB_METADATA_FINALIZER_JAVADOCFINALIZER_OVERLOADS_HPP +#define MRDOCS_LIB_METADATA_FINALIZER_JAVADOCFINALIZER_OVERLOADS_HPP + +#include "lib/Lib/CorpusImpl.hpp" +#include "lib/Lib/Info.hpp" +#include "Function.hpp" +#include + +namespace clang::mrdocs { +namespace { +auto +overloadFunctionsRange(OverloadsInfo const& O, CorpusImpl& corpus_) +{ + // Create a view all Info members of O + auto functions = + O.Members | + std::views::transform([&](SymbolID const& id) + { + return corpus_.find(id); + }) | + std::views::filter([](Info const* infoPtr) + { + return infoPtr != nullptr && infoPtr->isFunction(); + }) | + std::views::transform([](Info const* infoPtr) -> FunctionInfo const& + { + return *dynamic_cast(infoPtr); + }); + return functions; +} + +template +bool +populateOverloadsBriefIfAllSameBrief(OverloadsInfo& I, Range&& functionsWithBrief) +{ + auto first = *functionsWithBrief.begin(); + doc::Brief const& firstBrief = *first.javadoc->brief; + if (auto otherFunctions = std::views::drop(functionsWithBrief, 1); + std::ranges::all_of(otherFunctions, [&](FunctionInfo const& otherFunction) + { + doc::Brief const& otherBrief = *otherFunction.javadoc->brief; + return otherBrief.children == firstBrief.children; + })) + { + I.javadoc->brief = firstBrief; + return true; + } + return false; +} + +bool +populateOverloadsFromClass(OverloadsInfo& I) +{ + switch (I.Class) + { + case FunctionClass::Normal: + return false; + case FunctionClass::Constructor: + { + I.javadoc->brief = "Constructors"; + return true; + } + case FunctionClass::Conversion: + { + I.javadoc->brief = "Conversion operators"; + return true; + } + case FunctionClass::Destructor: + default: + MRDOCS_UNREACHABLE(); + } +} + +template +bool +populateOverloadsFromOperator(OverloadsInfo& I, Range&& functions) +{ + MRDOCS_CHECK_OR(I.OverloadedOperator != OperatorKind::None, false); + + // Stream insertion operators are implemented as an exception to the operator name + if (I.OverloadedOperator == OperatorKind::LessLess && + std::ranges::all_of(functions, isStreamInsertion)) + { + I.javadoc->brief = "Stream insertion operators"; + return true; + } + + // Find the operator name + auto isBinary = [&](FunctionInfo const& function) { + return (function.Params.size() + function.IsRecordMethod) == 2; + }; + auto isAllBinary = std::ranges::all_of(functions, isBinary); + int const nParams = isAllBinary ? 2 : 1; + auto const res = getOperatorReadableName(I.OverloadedOperator, nParams); + MRDOCS_CHECK_OR(res, false); + std::string briefStr(*res); + briefStr += " operators"; + I.javadoc->brief = std::move(briefStr); + return true; +} + +bool +populateOverloadsFromFunctionName(OverloadsInfo& I) +{ + std::string name = I.Name; + if (name.empty() && + I.OverloadedOperator != OperatorKind::None) + { + name = getOperatorName(I.OverloadedOperator, true); + } + if (name.empty()) + { + return false; + } + I.javadoc->brief.emplace(); + I.javadoc->brief->children.emplace_back(MakePolymorphic(std::string(name), doc::Style::mono)); + I.javadoc->brief->children.emplace_back(MakePolymorphic(std::string(" overloads"))); + return true; +} + +template +void +populateOverloadsBrief(OverloadsInfo& I, Range&& functions, CorpusImpl& corpus) +{ + auto functionsWithBrief = std::views:: + filter(functions, [](FunctionInfo const& function) { + return function.javadoc && function.javadoc->brief + && !function.javadoc->brief->empty(); + }); + auto anyMemberBrief = !std::ranges::empty(functionsWithBrief); + if (!corpus.config->autoFunctionMetadata && + !anyMemberBrief) + { + // If there are no briefs, and we'll not populate the briefs + // from function names, we'll also not populate the briefs + // of the overload set. + return; + } + if (anyMemberBrief) + { + MRDOCS_CHECK_OR(!populateOverloadsBriefIfAllSameBrief(I, functionsWithBrief)); + } + MRDOCS_CHECK_OR(!populateOverloadsFromClass(I)); + MRDOCS_CHECK_OR(!populateOverloadsFromOperator(I, functions)); + if (anyMemberBrief) + { + // We recur to the function name when the briefs are in conflict + // If there are no briefs, we don't consider it a conflict + // We just leave the overload set also without a brief + MRDOCS_CHECK_OR(!populateOverloadsFromFunctionName(I)); + } +} + +// Populate with all the unique "returns" from the functions +template +void +populateOverloadsReturns(OverloadsInfo& I, Range&& functions) { + auto functionReturns = functions | + std::views::filter([](FunctionInfo const& function) + { + return function.javadoc && !function.javadoc->returns.empty(); + }) | + std::views::transform([](FunctionInfo const& function) + { + return function.javadoc->returns; + }) | + std::views::join; + for (doc::Returns const& functionReturn: functionReturns) + { + auto sameIt = std::ranges::find_if( + I.javadoc->returns, + [&functionReturn](doc::Returns const& overloadReturns) + { + return overloadReturns == functionReturn; + }); + if (sameIt == I.javadoc->returns.end()) + { + I.javadoc->returns.push_back(functionReturn); + } + } +} + +template +void +populateOverloadsParams(OverloadsInfo& I, Range& functions) { + auto functionParams = functions | + std::views::filter([](FunctionInfo const& function) + { + return function.javadoc && !function.javadoc->params.empty(); + }) | + std::views::transform([](FunctionInfo const& function) + { + return function.javadoc->params; + }) | + std::views::join; + for (doc::Param const& functionParam: functionParams) + { + auto sameIt = std::ranges::find_if( + I.javadoc->params, + [&functionParam](doc::Param const& overloadParam) + { + return overloadParam.name == functionParam.name; + }); + if (sameIt == I.javadoc->params.end()) + { + I.javadoc->params.push_back(functionParam); + } + } +} + +template +void +populateOverloadsTParams(OverloadsInfo& I, Range& functions) { + auto functionTParams = functions | + std::views::filter([](FunctionInfo const& function) + { + return function.javadoc && !function.javadoc->tparams.empty(); + }) | + std::views::transform([](FunctionInfo const& function) + { + return function.javadoc->tparams; + }) | + std::views::join; + for (doc::TParam const& functionTParam: functionTParams) + { + auto sameIt = std::ranges::find_if( + I.javadoc->tparams, + [&functionTParam](doc::TParam const& overloadTParam) + { + return overloadTParam.name == functionTParam.name; + }); + if (sameIt == I.javadoc->tparams.end()) + { + I.javadoc->tparams.push_back(functionTParam); + } + } +} + +template +void +populateOverloadsExceptions(OverloadsInfo& I, Range& functions) { + auto functionExceptions = functions | + std::views::filter([](FunctionInfo const& function) + { + return function.javadoc && !function.javadoc->exceptions.empty(); + }) | + std::views::transform([](FunctionInfo const& function) + { + return function.javadoc->exceptions; + }) | + std::views::join; + for (doc::Throws const& functionException: functionExceptions) + { + auto sameIt = std::ranges::find_if( + I.javadoc->exceptions, + [&functionException](doc::Throws const& overloadException) + { + return overloadException.exception.string == functionException.exception.string; + }); + if (sameIt == I.javadoc->exceptions.end()) + { + I.javadoc->exceptions.push_back(functionException); + } + } +} + +template +void +populateOverloadsSees(OverloadsInfo& I, Range& functions) { + auto functionSees = functions | + std::views::filter([](FunctionInfo const& function) + { + return function.javadoc && !function.javadoc->sees.empty(); + }) | + std::views::transform([](FunctionInfo const& function) + { + return function.javadoc->sees; + }) | + std::views::join; + for (doc::See const& functionSee: functionSees) + { + auto sameIt = std::ranges::find_if( + I.javadoc->sees, + [&functionSee](doc::See const& overloadSee) + { + return overloadSee.children == functionSee.children; + }); + if (sameIt == I.javadoc->sees.end()) + { + I.javadoc->sees.push_back(functionSee); + } + } +} + +template +void +populateOverloadsPreconditions(OverloadsInfo& I, Range& functions) { + auto functionsPres = functions | + std::views::filter([](FunctionInfo const& function) + { + return function.javadoc && !function.javadoc->preconditions.empty(); + }) | + std::views::transform([](FunctionInfo const& function) + { + return function.javadoc->preconditions; + }) | + std::views::join; + for (doc::Precondition const& functionPre: functionsPres) + { + auto sameIt = std::ranges::find_if( + I.javadoc->preconditions, + [&functionPre](doc::Precondition const& overloadPre) + { + return overloadPre.children == functionPre.children; + }); + if (sameIt == I.javadoc->preconditions.end()) + { + I.javadoc->preconditions.push_back(functionPre); + } + } +} + +template +void +populateOverloadsPostconditions(OverloadsInfo& I, Range& functions) { + auto functionsPosts = functions | + std::views::filter([](FunctionInfo const& function) + { + return function.javadoc && !function.javadoc->postconditions.empty(); + }) | + std::views::transform([](FunctionInfo const& function) + { + return function.javadoc->postconditions; + }) | + std::views::join; + for (doc::Postcondition const& functionPost: functionsPosts) + { + auto sameIt = std::ranges::find_if( + I.javadoc->postconditions, + [&functionPost](doc::Postcondition const& overloadPost) + { + return overloadPost.children == functionPost.children; + }); + if (sameIt == I.javadoc->postconditions.end()) + { + I.javadoc->postconditions.push_back(functionPost); + } + } +} + +} +} // clang::mrdocs + +#endif diff --git a/src/lib/Metadata/Finalizers/JavadocFinalizer.cpp b/src/lib/Metadata/Finalizers/JavadocFinalizer.cpp index f80f638ae..dd0eee3f2 100644 --- a/src/lib/Metadata/Finalizers/JavadocFinalizer.cpp +++ b/src/lib/Metadata/Finalizers/JavadocFinalizer.cpp @@ -10,768 +10,968 @@ // #include "JavadocFinalizer.hpp" +#include "Javadoc/Overloads.hpp" +#include "Javadoc/Function.hpp" #include #include #include namespace clang::mrdocs { -template void JavadocFinalizer:: -operator()(InfoTy& I) +build() { - MRDOCS_CHECK_OR(!finalized_.contains(&I)); - finalized_.emplace(&I); - - if constexpr (InfoTy::isOverloads()) - { - if (!I.javadoc) - { - populateOverloadJavadocs(I); + // This function finalizes groups of javadoc components in + // different loops. This allows us to resolve references + // that are only related to that component group without + // creating circular dependencies. + + // Finalize briefs: + // We do it first because all other steps require accessing + // the brief of other functions, these often need to be resolved + // with @copybrief or auto-brief, and we need to ensure that + // there are no circular dependencies for other metadata. + for (auto& infoPtr : corpus_.info_) + { + MRDOCS_ASSERT(infoPtr); + Info& I = *infoPtr; + MRDOCS_CHECK_OR_CONTINUE(I.Extraction != ExtractionMode::Dependency); + finalizeBrief(I); + } + + // Finalize metadata: + // A @copydetails command also implies we should copy + // other metadata from the referenced symbol. + // We do it now because we need the complete metadata + // for all objects to generate javadoc for overloads. + // For instance, overloads cannot aggregate function + // parameters as if the parameters are not resolved. + for (auto& infoPtr : corpus_.info_) + { + MRDOCS_ASSERT(infoPtr); + Info& I = *infoPtr; + MRDOCS_CHECK_OR_CONTINUE(I.Extraction != ExtractionMode::Dependency); + finalizeMetadataCopies(I); + } + + // Create javadoc for overloads + // - We do it before the references because the overloads + // themselves can be used in the references. For instance, + // `@ref foo` refers to the overload set because it doesn't + // specify the function signature. + if (corpus_.config->overloads) + { + for (auto& infoPtr : corpus_.info_) + { + MRDOCS_ASSERT(infoPtr); + Info& I = *infoPtr; + MRDOCS_CHECK_OR_CONTINUE(I.isOverloads()); + MRDOCS_CHECK_OR_CONTINUE(I.Extraction != ExtractionMode::Dependency); + if (!I.javadoc) + { + I.javadoc.emplace(); + } + populateOverloadJavadoc(dynamic_cast(*infoPtr)); } } - report::trace( - "Finalizing javadoc for '{}'", - corpus_.Corpus::qualifiedName(I)); - - ScopeExitRestore s(current_context_, &I); - - // Finalize references in javadoc - finalize(I.javadoc); - - finalizeInfoData(I); -} - -#define INFO(T) template void JavadocFinalizer::operator()(T## Info&); -#include - -template -void -JavadocFinalizer:: -finalizeInfoData(InfoTy& I) -{ -#ifndef NDEBUG - // Check references - if (I.Parent) - { - checkExists(I.Parent); - } - if constexpr (InfoParent) + // Resolve references in the javadoc + for (auto& infoPtr : corpus_.info_) { - checkExists(allMembers(I)); + MRDOCS_ASSERT(infoPtr); + Info& I = *infoPtr; + MRDOCS_CHECK_OR_CONTINUE(I.Extraction != ExtractionMode::Dependency); + finalizeJavadoc(I); } -#endif - if constexpr (requires { I.UsingDirectives; }) - { - finalize(I.UsingDirectives); - } - if constexpr (requires { I.Template; }) - { - finalize(I.Template); - } - if constexpr (requires { I.Bases; }) - { - finalize(I.Bases); - } - if constexpr (requires { I.Primary; }) - { - finalize(I.Primary); - } - if constexpr (requires { I.Args; }) - { - finalize(I.Args); - } - if constexpr (requires { I.ReturnType; }) - { - finalize(I.ReturnType); - } - if constexpr (requires { I.Params; }) - { - finalize(I.Params); - } - if constexpr (requires { I.Type; }) - { - finalize(I.Type); - } - if constexpr (requires { I.UnderlyingType; }) - { - finalize(I.UnderlyingType); - } - if constexpr (requires { I.FriendSymbol; }) - { - finalize(I.FriendSymbol); - } - if constexpr (requires { I.FriendType; }) - { - finalize(I.FriendType); - } - if constexpr (requires { I.AliasedSymbol; }) - { - finalize(I.AliasedSymbol); - } - if constexpr (requires { I.Qualifier; }) - { - finalize(I.Qualifier); - } - if constexpr (requires { I.UsingSymbols; }) + // Populate trivial function metadata + // - We do it after the overloads because they should not + // rely on metadata inherited from automatic generated javadoc + // - We also do it after the references because some metadata + // might be resolved from references with @copydetails + if (corpus_.config->autoFunctionMetadata) { - finalize(I.UsingSymbols); + for (auto& infoPtr : corpus_.info_) + { + MRDOCS_ASSERT(infoPtr); + Info& I = *infoPtr; + MRDOCS_CHECK_OR_CONTINUE(I.isFunction()); + MRDOCS_CHECK_OR_CONTINUE(I.Extraction != ExtractionMode::Dependency); + populateFunctionJavadoc(dynamic_cast(I)); + } } - if constexpr (requires { I.Deduced; }) + + // Remove invalid references in the Info objects + for (auto& infoPtr : corpus_.info_) { - finalize(I.Deduced); + MRDOCS_ASSERT(infoPtr); + Info& I = *infoPtr; + visit(I, [&](auto& U) { + finalizeInfoData(U); + }); } -} -#define INFO(T) template void JavadocFinalizer::finalizeInfoData(T## Info&); -#include + // - Emitting param warning require everything to be completely + // processed + emitWarnings(); +} void JavadocFinalizer:: -finalize(doc::Reference& ref, bool const emitWarning) +finalizeBrief(Info& I) { - if (ref.id != SymbolID::invalid) + MRDOCS_CHECK_OR(!finalized_brief_.contains(&I)); + finalized_brief_.emplace(&I); + ScopeExitRestore s(current_context_, &I); + + report::trace( + "Finalizing brief for '{}'", + corpus_.Corpus::qualifiedName(I)); + + if (I.isOverloads()) { - // Already resolved + // Overloads are expected not to have javadoc. + // We'll create a javadoc for them if they don't have one. + if (!I.javadoc) + { + I.javadoc.emplace(); + } + // The brief of an overload is always empty + auto& OI = dynamic_cast(I); + for (auto& MemberIDs = OI.Members; + auto& memberID : MemberIDs) + { + Info* member = corpus_.find(memberID); + MRDOCS_CHECK_OR_CONTINUE(member); + finalizeBrief(*member); + } + auto functions = overloadFunctionsRange(OI, corpus_); + populateOverloadsBrief(OI, functions, corpus_); return; } - if (auto resRef = corpus_.lookup(current_context_->id, ref.string)) - { - // KRYSTIAN NOTE: we should provide an overload that - // returns a non-const reference. - auto& res = const_cast(resRef->get()); - ref.id = res.id; - } - else if ( - emitWarning && - corpus_.config->warnings && - corpus_.config->warnBrokenRef && - // Only warn once per reference - !refWarned_.contains({ref.string, current_context_->Name}) && - // Ignore std:: references - !ref.string.starts_with("std::") && - // Ignore other reference types that can't be replaced by `...` - ref.Kind == doc::NodeKind::reference) - { - MRDOCS_ASSERT(current_context_); - this->warn( - "{}: Failed to resolve reference to '{}'\n" - " {}", - corpus_.Corpus::qualifiedName(*current_context_), - ref.string, - resRef.error().reason()); - refWarned_.insert({ref.string, current_context_->Name}); - } + + MRDOCS_CHECK_OR(I.javadoc); + // Copy brief from other symbols if there's a @copydoc + copyBrief(*I.javadoc); + // Set auto brief if brief is still empty + setAutoBrief(*I.javadoc); } void JavadocFinalizer:: -finalize(doc::Node& node) +copyBrief(Javadoc& javadoc) { - visit(node, [&](NodeTy& N) + MRDOCS_CHECK_OR(javadoc.brief); + MRDOCS_CHECK_OR(!javadoc.brief->copiedFrom.empty()); + MRDOCS_CHECK_OR(javadoc.brief->children.empty()); + + for (std::string const& ref: javadoc.brief->copiedFrom) { - if constexpr (requires { N.children; }) - { - finalize(N.children); - } + // Look for source + auto resRef = + corpus_.lookup(current_context_->id, ref); - if constexpr(std::same_as) + // Check if the source exists + if (!resRef) { - finalize(dynamic_cast(N), true); + if (corpus_.config->warnings && + corpus_.config->warnBrokenRef && + !refWarned_.contains({ref, current_context_->Name})) + { + this->warn( + "{}: Failed to copy brief from '{}' (symbol not found)\n" + " {}", + corpus_.Corpus::qualifiedName(*current_context_), + ref, + resRef.error().reason()); + } + continue; } - else if constexpr (std::same_as) + + // Ensure the brief source is finalized + Info const& res = *resRef; + finalizeBrief(const_cast(res)); + + // Check if the source has a brief + if (!res.javadoc || + !res.javadoc->brief.has_value()) { - finalize(dynamic_cast(N).exception, false); + if (corpus_.config->warnings && + corpus_.config->warnBrokenRef && + !refWarned_.contains({ref, current_context_->Name})) + { + auto resPrimaryLoc = getPrimaryLocation(res); + this->warn( + "{}: Failed to copy brief from {} '{}' (no brief available).\n" + " No brief available.\n" + " {}:{}\n" + " Note: No brief available for '{}'.", + corpus_.Corpus::qualifiedName(*current_context_), + toString(res.Kind), + ref, + resPrimaryLoc->FullPath, + resPrimaryLoc->LineNumber, + corpus_.Corpus::qualifiedName(res)); + } + continue; } - }); + + Javadoc const& src = *res.javadoc; + javadoc.brief->children = src.brief->children; + return; + } } void JavadocFinalizer:: -finalize(Javadoc& javadoc) +setAutoBrief(Javadoc& javadoc) const { - finalize(javadoc.blocks); - finalize(javadoc.brief); - finalize(javadoc.returns); - finalize(javadoc.params); - finalize(javadoc.tparams); - finalize(javadoc.exceptions); - finalize(javadoc.sees); - finalize(javadoc.preconditions); - finalize(javadoc.postconditions); - processRelates(javadoc); - copyBriefAndDetails(javadoc); - setAutoBrief(javadoc); - removeTempTextNodes(javadoc); - trimBlocks(javadoc); - unindentCodeBlocks(javadoc); -} + MRDOCS_CHECK_OR(corpus_.config->autoBrief); + MRDOCS_CHECK_OR(!javadoc.brief); + MRDOCS_CHECK_OR(!javadoc.blocks.empty()); -namespace { -bool -referenceCmp( - doc::Reference const& lhs, - doc::Reference const& rhs) { - bool const lhsIsGlobal = lhs.string.starts_with("::"); - bool const rhsIsGlobal = rhs.string.starts_with("::"); - if (lhsIsGlobal != rhsIsGlobal) - { - return lhsIsGlobal < rhsIsGlobal; - } - std::size_t const lhsCount = std::ranges::count(lhs.string, ':'); - std::size_t const rhsCount = std::ranges::count(rhs.string, ':'); - if (lhsCount != rhsCount) - { - return lhsCount < rhsCount; - } - if (lhs.string != rhs.string) + auto isInvalidBriefText = [](Polymorphic const& text) { + return !text || text->string.empty() + || text->Kind == doc::NodeKind::copy_details + || isWhitespace(text->string); + }; + + for (auto it = javadoc.blocks.begin(); it != javadoc.blocks.end();) { - return lhs.string < rhs.string; + if (auto& block = *it; + block->Kind == doc::NodeKind::paragraph || + block->Kind == doc::NodeKind::details) + { + auto& para = dynamic_cast(*block); + if (std::ranges::all_of(para.children, isInvalidBriefText)) + { + ++it; + continue; + } + javadoc.brief.emplace(); + javadoc.brief->children = para.children; + it = javadoc.blocks.erase(it); + return; + } + ++it; } - return lhs.id < rhs.id; +} + +namespace { +TemplateInfo const* +getTemplateInfo(Info& I) +{ + return visit(I, [](auto& I) -> TemplateInfo const* { + if constexpr (requires { I.Template; }) + { + if (I.Template) + { + return &*I.Template; + } + } + return nullptr; + }); } } void JavadocFinalizer:: -processRelates(Javadoc& javadoc) +finalizeMetadataCopies(Info& I) { - if (corpus_.config->autoRelates) - { - setAutoRelates(); - } + MRDOCS_CHECK_OR(!finalized_metadata_.contains(&I)); + finalized_metadata_.emplace(&I); + ScopeExitRestore s(current_context_, &I); - MRDOCS_CHECK_OR(!javadoc.relates.empty()); + report::trace( + "Finalizing metadata for '{}'", + corpus_.Corpus::qualifiedName(I)); - Info const* currentPtr = corpus_.find(current_context_->id); - MRDOCS_ASSERT(currentPtr); - Info const current = *currentPtr; + MRDOCS_CHECK_OR(I.javadoc); + MRDOCS_CHECK_OR(!I.javadoc->blocks.empty()); + Javadoc& destJavadoc = *I.javadoc; - if (!current.isFunction()) + SmallVector copiedRefs; + for (auto& block: destJavadoc.blocks) { - this->warn( - "{}: `@relates` only allowed for functions", - corpus_.Corpus::qualifiedName(current)); - javadoc.relates.clear(); - return; + MRDOCS_CHECK_OR_CONTINUE( + block->Kind == doc::NodeKind::paragraph + || block->Kind == doc::NodeKind::details); + auto& para = dynamic_cast(*block); + MRDOCS_CHECK_OR_CONTINUE(!para.children.empty()); + + for (auto& text: para.children) + { + MRDOCS_CHECK_OR_CONTINUE(text->Kind == doc::NodeKind::copy_details); + copiedRefs.emplace_back(dynamic_cast(*text)); + } + MRDOCS_CHECK_OR_CONTINUE(!copiedRefs.empty()); } - for (doc::Reference& ref: javadoc.relates) + for (doc::CopyDetails const& copied: copiedRefs) { - finalize(ref, true); - Info* relatedPtr = corpus_.find(ref.id); - MRDOCS_CHECK_OR_CONTINUE(relatedPtr); - Info& related = *relatedPtr; - if (!related.javadoc) + // Find element + auto resRef = corpus_.lookup(current_context_->id, copied.string); + if (!resRef) { - related.javadoc.emplace(); + if (corpus_.config->warnings && + corpus_.config->warnBrokenRef && + !refWarned_.contains({copied.string, current_context_->Name})) + { + this->warn( + "{}: Failed to copy metadata from '{}' (symbol not found)\n" + " {}", + corpus_.Corpus::qualifiedName(*current_context_), + copied.string, + resRef.error().reason()); + } + continue; } - if (std::ranges::none_of( - related.javadoc->related, - [this](doc::Reference const& otherRef) { - return otherRef.id == current_context_->id; - })) + + // Function to copy the metadata from a ranges + // of source functions. This range might + // contain more than one function if the + // destination is an overload set. + // We can't copy directly from the overload set + // because its metadata is not created at this + // step yet. + auto copyInfoRangeMetadata = [&](ArrayRef srcInfoPtrs) { - std::string currentName = corpus_.Corpus::qualifiedName(current, relatedPtr->Parent); - doc::Reference relatedRef(std::move(currentName)); - relatedRef.id = current_context_->id; - // Insert in order by name - auto const it = std::ranges::lower_bound( - related.javadoc->related, - relatedRef, - referenceCmp); - related.javadoc->related.insert(it, std::move(relatedRef)); - } - } + auto srcInfos = srcInfoPtrs + | std::views::transform( + [](Info const* ptr) -> Info const& { + return *ptr; + }); - // Erase anything in the javadoc without a valid id - std::erase_if(javadoc.relates, [](doc::Reference const& ref) { - return !ref.id; - }); -} + // Ensure the source metadata is finalized + for (auto& srcInfo: srcInfos) + { + auto& mutSrcInfo = const_cast(srcInfo); + finalizeMetadataCopies(mutSrcInfo); + } -namespace { -void -pushAllDerivedClasses( - RecordInfo const* record, - SmallVector& relatedRecordsOrEnums, - CorpusImpl& corpus) -{ - for (auto& derivedId : record->Derived) - { - Info* derivedPtr = corpus.find(derivedId); - MRDOCS_CHECK_OR_CONTINUE(derivedPtr); - MRDOCS_CHECK_OR_CONTINUE(derivedPtr->Extraction == ExtractionMode::Regular); - auto derived = dynamic_cast(derivedPtr); - MRDOCS_CHECK_OR_CONTINUE(derived); - relatedRecordsOrEnums.push_back(derived); - // Recursively get derived classes of the derived class - pushAllDerivedClasses(derived, relatedRecordsOrEnums, corpus); - } -} -} + // Copy returns only if destination is empty + if (destJavadoc.returns.empty()) + { + for (auto const& srcInfo: srcInfos) + { + MRDOCS_CHECK_OR_CONTINUE(srcInfo.javadoc); + for (doc::Returns const& returnsEl: srcInfo.javadoc->returns) + { + MRDOCS_CHECK_OR_CONTINUE(!contains(destJavadoc.returns, returnsEl)); + destJavadoc.returns.push_back(returnsEl); + } + } + } -void -JavadocFinalizer:: -setAutoRelates() -{ - MRDOCS_ASSERT(current_context_); - MRDOCS_CHECK_OR(current_context_->Extraction == ExtractionMode::Regular); - MRDOCS_CHECK_OR(current_context_->isFunction()); - MRDOCS_CHECK_OR(current_context_->javadoc); - auto& I = dynamic_cast(*current_context_); - MRDOCS_CHECK_OR(!I.IsRecordMethod); - auto* parentPtr = corpus_.find(I.Parent); - MRDOCS_CHECK_OR(parentPtr); - MRDOCS_CHECK_OR(parentPtr->isNamespace()); + // Copy only params that don't exist at the destination + // documentation but that do exist in the destination + // function parameters declaration. + if (I.isFunction()) + { + auto& destF = dynamic_cast(I); + for (Info const& srcInfo: srcInfos) + { + MRDOCS_CHECK_OR_CONTINUE(srcInfo.isFunction()); + auto const& srcFunction = dynamic_cast(srcInfo); + MRDOCS_CHECK_OR_CONTINUE(srcFunction.javadoc); + for (Javadoc const& srcJavadoc = *srcFunction.javadoc; + auto const& srcDocParam: srcJavadoc.params) + { + // check if param doc doesn't already exist + MRDOCS_CHECK_OR_CONTINUE( + std::ranges::none_of( + destJavadoc.params, + [&srcDocParam](doc::Param const& destDocParam) { + return srcDocParam.name == destDocParam.name; + })); + + // check if param name exists in the destination function + MRDOCS_CHECK_OR_CONTINUE( + std::ranges::any_of( + destF.Params, + [&srcDocParam](Param const& destParam) { + return srcDocParam.name == *destParam.Name; + })); + + // Push the new param ot the + destJavadoc.params.push_back(srcDocParam); + } + } + } - auto toRecordOrEnum = [&](Polymorphic const& type) -> Info* { - MRDOCS_CHECK_OR(type, nullptr); - auto& innermost = innermostType(type); - MRDOCS_CHECK_OR(innermost, nullptr); - MRDOCS_CHECK_OR(innermost->isNamed(), nullptr); - auto const& namedType = dynamic_cast(*innermost); - MRDOCS_CHECK_OR(namedType.Name, nullptr); - SymbolID const namedSymbolID = namedType.Name->id; - MRDOCS_CHECK_OR(namedSymbolID != SymbolID::invalid, nullptr); - Info* infoPtr = corpus_.find(namedSymbolID); - MRDOCS_CHECK_OR(infoPtr, nullptr); - MRDOCS_CHECK_OR( - infoPtr->isRecord() || - infoPtr->isEnum(), nullptr); - return infoPtr; - }; + // Copy only tparams that don't exist at the destination + // documentation but that do exist in the destination + // template parameters. + if (auto const destTemplateInfo = getTemplateInfo(I)) + { + for (Info const& srcInfo: srcInfos) + { + MRDOCS_CHECK_OR_CONTINUE(srcInfo.javadoc); + for (Javadoc const& srcJavadoc = *srcInfo.javadoc; + auto const& srcTParam: srcJavadoc.tparams) + { + // tparam doesn't already exist at the destination + MRDOCS_CHECK_OR_CONTINUE( + std::ranges::none_of( + destJavadoc.tparams, + [&srcTParam](doc::TParam const& destTParam) { + return srcTParam.name == destTParam.name; + })); + + // TParam name exists in the destination definition + MRDOCS_CHECK_OR_CONTINUE( + std::ranges::any_of( + destTemplateInfo->Params, + [&srcTParam]( + Polymorphic const& destTParam) { + return srcTParam.name == destTParam->Name; + })); - SmallVector relatedRecordsOrEnums; + // Push the new param + destJavadoc.tparams.push_back(srcTParam); + } + } + } - // 1) Inner type of the first parameter - [&] { - MRDOCS_CHECK_OR(!I.Params.empty()); - auto* firstParamInfo = toRecordOrEnum(I.Params.front().Type); - MRDOCS_CHECK_OR(firstParamInfo); - if (firstParamInfo->Extraction == ExtractionMode::Regular) - { - relatedRecordsOrEnums.push_back(firstParamInfo); - } - // 2) If the type is a reference or a pointer, derived classes - // of this inner type are also valid related records - MRDOCS_CHECK_OR(firstParamInfo->isRecord()); - auto const* firstParamRecord = dynamic_cast(firstParamInfo); - MRDOCS_CHECK_OR( - I.Params.front().Type->isLValueReference() || - I.Params.front().Type->isRValueReference() || - I.Params.front().Type->isPointer()); - // Get all transitively derived classes of firstParamRecord - pushAllDerivedClasses(firstParamRecord, relatedRecordsOrEnums, corpus_); - }(); + // Copy exceptions only if destination exceptions are empty + // and the destination is not noexcept + bool const destIsNoExcept = + I.isFunction() ? + dynamic_cast(I).Noexcept.Kind == NoexceptKind::False : + false; + if (destJavadoc.exceptions.empty() && + !destIsNoExcept) + { + for (Info const& srcInfo: srcInfos) + { + MRDOCS_CHECK_OR_CONTINUE(srcInfo.javadoc); + for (doc::Throws const& exceptionsEl: srcInfo.javadoc->exceptions) + { + MRDOCS_CHECK_OR_CONTINUE(!contains(destJavadoc.exceptions, exceptionsEl)); + destJavadoc.exceptions.push_back(exceptionsEl); + } + } + } - // 3) The return type of the function - if (auto* returnTypeInfo = toRecordOrEnum(I.ReturnType)) - { - if (returnTypeInfo->Extraction == ExtractionMode::Regular) - { - relatedRecordsOrEnums.push_back(returnTypeInfo); - } - // 4) If the return type is a template specialization, - // and the template parameters are records, then - // each template parameter is also a related record - [&] { - MRDOCS_CHECK_OR(I.ReturnType); - MRDOCS_CHECK_OR(I.ReturnType->isNamed()); - auto& NTI = get(I.ReturnType); - MRDOCS_CHECK_OR(NTI.Name); - MRDOCS_CHECK_OR(NTI.Name->isSpecialization()); - auto const& NTIS = get(NTI.Name); - MRDOCS_CHECK_OR(!NTIS.TemplateArgs.empty()); - Polymorphic const& firstArg = NTIS.TemplateArgs.front(); - MRDOCS_CHECK_OR(firstArg->isType()); - auto const& typeArg = get(firstArg); - if (auto* argInfo = toRecordOrEnum(typeArg.Type)) + // Copy sees only if destination sees are empty + if (destJavadoc.sees.empty()) { - if (argInfo->Extraction == ExtractionMode::Regular) + for (Info const& srcInfo: srcInfos) { - relatedRecordsOrEnums.push_back(argInfo); + MRDOCS_CHECK_OR_CONTINUE(srcInfo.javadoc); + for (doc::See const& seesEl: srcInfo.javadoc->sees) + { + MRDOCS_CHECK_OR_CONTINUE(!contains(destJavadoc.sees, seesEl)); + destJavadoc.sees.push_back(seesEl); + } } } - }(); - } - // Remove duplicates from relatedRecordsOrEnums - std::ranges::sort(relatedRecordsOrEnums); - relatedRecordsOrEnums.erase( - std::ranges::unique(relatedRecordsOrEnums).begin(), - relatedRecordsOrEnums.end()); + // Copy preconditions only if destination preconditions is empty + if (destJavadoc.preconditions.empty()) + { + for (Info const& srcInfo: srcInfos) + { + MRDOCS_CHECK_OR_CONTINUE(srcInfo.javadoc); + for (doc::Precondition const& preconditionsEl: srcInfo.javadoc->preconditions) + { + MRDOCS_CHECK_OR_CONTINUE(!contains(destJavadoc.preconditions, preconditionsEl)); + destJavadoc.preconditions.push_back(preconditionsEl); + } + } + } - // Insert the records with valid ids into the javadoc relates section - std::size_t const prevRelatesSize = I.javadoc->relates.size(); - for (Info const* relatedRecordOrEnumPtr : relatedRecordsOrEnums) - { - MRDOCS_CHECK_OR_CONTINUE(relatedRecordOrEnumPtr); - MRDOCS_ASSERT(I.javadoc); - Info const& recordOrEnum = *relatedRecordOrEnumPtr; - MRDOCS_CHECK_OR_CONTINUE(recordOrEnum.Extraction == ExtractionMode::Regular); - doc::Reference ref(recordOrEnum.Name); - ref.id = recordOrEnum.id; + // Copy postconditions only if destination postconditions is empty + if (destJavadoc.postconditions.empty()) + { + for (Info const& srcInfo: srcInfos) + { + MRDOCS_CHECK_OR_CONTINUE(srcInfo.javadoc); + for (doc::Postcondition const& postconditionsEl: + srcInfo.javadoc->postconditions) + { + MRDOCS_CHECK_OR_CONTINUE(!contains( + destJavadoc.postconditions, + postconditionsEl)); + destJavadoc.postconditions.push_back(postconditionsEl); + } + } + } + }; - // Check if already listed as friend - if (auto* record = dynamic_cast(relatedRecordOrEnumPtr)) + // Ensure the source metadata is finalized + Info const& res = *resRef; + if (!res.isOverloads()) { - auto fromFriendIdToTypeID = [&](SymbolID const& id) -> SymbolID { - Info* friendInfo = corpus_.find(id); - MRDOCS_CHECK_OR(friendInfo, SymbolID::invalid); - auto const friendPtr = dynamic_cast(friendInfo); - MRDOCS_CHECK_OR(friendPtr, SymbolID::invalid); - return friendPtr->FriendSymbol; - }; - using std::views::transform; - if (contains(transform(record->Interface.Public.Friends, fromFriendIdToTypeID), I.id)) + // If it's a single element, we check the element javadoc + if (!res.javadoc) { - // Already listed as a public friend + if (corpus_.config->warnings && + corpus_.config->warnBrokenRef && + !refWarned_.contains({copied.string, current_context_->Name})) + { + auto resPrimaryLoc = getPrimaryLocation(res); + this->warn( + "{}: Failed to copy metadata from {} '{}' (no documentation available).\n" + " No metadata available.\n" + " {}:{}\n" + " Note: No documentation available for '{}'.", + corpus_.Corpus::qualifiedName(*current_context_), + toString(res.Kind), + copied.string, + resPrimaryLoc->FullPath, + resPrimaryLoc->LineNumber, + corpus_.Corpus::qualifiedName(res)); + } continue; } + SmallVector srcInfos = { &res }; + copyInfoRangeMetadata(srcInfos); } - - // Ensure no duplicates - if (std::ranges::none_of( - I.javadoc->relates, - [&ref](doc::Reference const& otherRef) { - return otherRef.string == ref.string || otherRef.id == ref.id; - })) + else { - // Insert in order by name - auto const it = std::ranges::lower_bound( - I.javadoc->relates.begin() + prevRelatesSize, - I.javadoc->relates.end(), - ref, - referenceCmp); - I.javadoc->relates.insert(it, std::move(ref)); + auto& OI = dynamic_cast(res); + SmallVector srcInfos; + srcInfos.reserve(OI.Members.size()); + for (auto& memberID: OI.Members) + { + Info* member = corpus_.find(memberID); + MRDOCS_CHECK_OR_CONTINUE(member); + srcInfos.push_back(member); + } + copyInfoRangeMetadata(srcInfos); } } } void JavadocFinalizer:: -copyBriefAndDetails(Javadoc& javadoc) +populateFunctionJavadoc(FunctionInfo& I) const { - for (auto blockIt = javadoc.blocks.begin(); blockIt != javadoc.blocks.end();) + // For special functions (constructors, destructors, ...), + // we create the javadoc if it does not exist because + // we can populate all the fields from the function category. + // For other types of functions, we'll only populate + // the missing fields when the javadoc already exists. + bool const isSpecial = isSpecialFunction(I); + MRDOCS_CHECK_OR(isSpecial || I.javadoc); + bool forceEmplaced = false; + if (isSpecial && + !I.javadoc) { - auto& block = *blockIt; - if (block->Kind != doc::NodeKind::paragraph && - block->Kind != doc::NodeKind::details) + I.javadoc.emplace(); + forceEmplaced = true; + } + + // Populate a missing javadoc brief + populateFunctionBrief(I, corpus_); + + // Populate a missing javadoc returns + populateFunctionReturns(I, corpus_); + + // Populate missing javadoc params + populateFunctionParams(I, corpus_); + + // If we forcefully created the javadoc, we need to + // check if the function was able to populate all the + // fields. If not, we'll remove the javadoc. + if (forceEmplaced) + { + // Check brief and returns + if (!I.javadoc->brief) { - ++blockIt; - continue; + I.javadoc.reset(); + return; } - auto& para = dynamic_cast(*block); - if (para.children.empty()) + + if (!is_one_of(I.Class, { + FunctionClass::Constructor, + FunctionClass::Destructor }) && + I.javadoc->returns.empty()) { - ++blockIt; - continue; + I.javadoc.reset(); + return; } - // Find copydoc command - std::optional copied; - for (auto textIt = para.children.begin(); textIt != para.children.end();) - { - // Find copydoc command - auto& text = *textIt; - if (text->Kind != doc::NodeKind::copied) - { - ++textIt; - continue; - } - // Copy reference - copied = dynamic_cast(*text); - // Remove copied node - /* it2 = */ para.children.erase(textIt); - break; - } - // Remove leading children from the paragraph that are - // either empty or only white spaces. We also ltrim - // the first child with content. - while (!para.children.empty()) + // Check params size + std::size_t const nNamedParams = std::ranges:: + count_if(I.Params, [](Param const& p) -> bool { + return p.Name.has_value(); + }); + auto const documentedParams = getJavadocParamNames(*I.javadoc); + if (nNamedParams != documentedParams.size()) { - if (para.children.front()->string.find_first_not_of(" \t\n\v\f\r") == std::string::npos) - { - para.children.erase(para.children.begin()); - } - else + I.javadoc.reset(); + return; + } + + // Check param names + if (!std::ranges::all_of(I.Params, [&](Param const& param) { + if (param.Name) { - para.children.front()->string = ltrim(para.children.front()->string); - break; + return contains(documentedParams, *param.Name); } - } - // Remove trailing children from the paragraph that are - // either empty or only white spaces. We also rtrim - // the last child with content. - while (!para.children.empty()) + return true; + })) { - if (para.children.back()->string.find_first_not_of(" \t\n\v\f\r") == std::string::npos) + I.javadoc.reset(); + } + } +} + +void +JavadocFinalizer:: +populateOverloadJavadoc(OverloadsInfo& I) +{ + // Create a view all Info members of I. + // The javadoc for these function should already be as + // complete as possible + auto functions = + I.Members | + std::views::transform([&](SymbolID const& id) { - para.children.pop_back(); - } - else + return corpus_.find(id); + }) | + std::views::filter([](Info const* infoPtr) { - para.children.back()->string = rtrim(para.children.back()->string); - break; - } - } - // Remove empty completely empty children from the paragraph - std::erase_if(para.children, [](Polymorphic const& child) { - return child->string.empty(); - }); - // Merge consecutive text nodes that have exactly the same terminal kind - for (auto textIt = para.children.begin(); textIt != para.children.end();) - { - auto& text = *textIt; - if (textIt != para.children.begin()) + return infoPtr != nullptr && infoPtr->isFunction(); + }) | + std::views::transform([](Info const* infoPtr) -> FunctionInfo const& { - if (auto& prev = *std::prev(textIt); - prev->Kind == text->Kind) - { - prev->string += text->string; - textIt = para.children.erase(textIt); - continue; - } - } - ++textIt; - } - // Remove the entire paragraph block from the javadoc if it is empty - if (para.empty()) - { - blockIt = javadoc.blocks.erase(blockIt); - MRDOCS_CHECK_OR_CONTINUE(copied); - } - if (!copied) - { - ++blockIt; - continue; - } + return *dynamic_cast(infoPtr); + }); + if (!I.javadoc) + { + I.javadoc.emplace(); + } - // Find the node to copy from - auto resRef = corpus_.lookup(current_context_->id, copied->string); - if (!resRef) + // briefs: populated in a previous step + // blocks: we do not copy javadoc detail blocks because + // it's impossible to guarantee that the details for + // any of the functions make sense for all overloads. + // We can only merge metadata. + populateOverloadsReturns(I, functions); + populateOverloadsParams(I, functions); + populateOverloadsTParams(I, functions); + populateOverloadsExceptions(I, functions); + populateOverloadsSees(I, functions); + populateOverloadsPreconditions(I, functions); + populateOverloadsPostconditions(I, functions); +} + +void +JavadocFinalizer:: +finalizeJavadoc(Info& I) +{ + MRDOCS_CHECK_OR(!finalized_.contains(&I)); + finalized_.emplace(&I); + ScopeExitRestore s(current_context_, &I); + + report::trace( + "Finalizing javadoc for '{}'", + corpus_.Corpus::qualifiedName(I)); + + if (I.javadoc) + { + finalize(*I.javadoc); + } +} + +template +void +JavadocFinalizer:: +finalizeInfoData(InfoTy& I) +{ +#ifndef NDEBUG + // Check references + if (I.Parent) + { + checkExists(I.Parent); + } + if constexpr (InfoParent) + { + checkExists(allMembers(I)); + } +#endif + + if constexpr (requires { I.UsingDirectives; }) + { + finalize(I.UsingDirectives); + } + if constexpr (requires { I.Template; }) + { + finalize(I.Template); + } + if constexpr (requires { I.Bases; }) + { + finalize(I.Bases); + } + if constexpr (requires { I.Primary; }) + { + finalize(I.Primary); + } + if constexpr (requires { I.Args; }) + { + finalize(I.Args); + } + if constexpr (requires { I.ReturnType; }) + { + finalize(I.ReturnType); + } + if constexpr (requires { I.Params; }) + { + finalize(I.Params); + } + if constexpr (requires { I.Type; }) + { + finalize(I.Type); + } + if constexpr (requires { I.UnderlyingType; }) + { + finalize(I.UnderlyingType); + } + if constexpr (requires { I.FriendSymbol; }) + { + finalize(I.FriendSymbol); + } + if constexpr (requires { I.FriendType; }) + { + finalize(I.FriendType); + } + if constexpr (requires { I.AliasedSymbol; }) + { + finalize(I.AliasedSymbol); + } + if constexpr (requires { I.Qualifier; }) + { + finalize(I.Qualifier); + } + if constexpr (requires { I.UsingSymbols; }) + { + finalize(I.UsingSymbols); + } + if constexpr (requires { I.Deduced; }) + { + finalize(I.Deduced); + } +} + +#define INFO(T) template void JavadocFinalizer::finalizeInfoData(T## Info&); +#include + +void +JavadocFinalizer:: +finalize(doc::Reference& ref, bool const emitWarning) +{ + if (ref.id != SymbolID::invalid) + { + // Already resolved + return; + } + if (auto resRef = corpus_.lookup(current_context_->id, ref.string)) + { + // KRYSTIAN NOTE: we should provide an overload that + // returns a non-const reference. + auto& res = const_cast(resRef->get()); + ref.id = res.id; + } + else if ( + emitWarning && + corpus_.config->warnings && + corpus_.config->warnBrokenRef && + // Only warn once per reference + !refWarned_.contains({ref.string, current_context_->Name}) && + // Ignore std:: references + !ref.string.starts_with("std::") && + // Ignore other reference types that can't be replaced by `...` + ref.Kind == doc::NodeKind::reference) + { + MRDOCS_ASSERT(current_context_); + this->warn( + "{}: Failed to resolve reference to '{}'\n" + " {}", + corpus_.Corpus::qualifiedName(*current_context_), + ref.string, + resRef.error().reason()); + refWarned_.insert({ref.string, current_context_->Name}); + } +} + +void +JavadocFinalizer:: +finalize(doc::Node& node) +{ + visit(node, [&](NodeTy& N) + { + if constexpr (requires { N.children; }) { - if (corpus_.config->warnings && - corpus_.config->warnBrokenRef && - !refWarned_.contains({copied->string, current_context_->Name})) - { - this->warn( - "{}: Failed to copy documentation from '{}' (symbol not found)\n" - " {}", - corpus_.Corpus::qualifiedName(*current_context_), - copied->string, - resRef.error().reason()); - } - continue; + finalize(N.children); } - // Ensure the source node is finalized - Info const& res = *resRef; - if (!finalized_.contains(&res)) + if constexpr(std::same_as) { - operator()(const_cast(res)); + finalize(dynamic_cast(N), true); } - if (!res.javadoc) + else if constexpr (std::same_as) { - if (corpus_.config->warnings && - corpus_.config->warnBrokenRef && - !refWarned_.contains({copied->string, current_context_->Name})) - { - auto resPrimaryLoc = getPrimaryLocation(res); - this->warn( - "{}: Failed to copy documentation from {} '{}' (no documentation available).\n" - " No documentation available.\n" - " {}:{}\n" - " Note: No documentation available for '{}'.", - corpus_.Corpus::qualifiedName(*current_context_), - toString(res.Kind), - copied->string, - resPrimaryLoc->FullPath, - resPrimaryLoc->LineNumber, - corpus_.Corpus::qualifiedName(res)); - } - continue; + finalize(dynamic_cast(N).exception, false); } + }); +} - // Copy brief and details - bool const copyBrief = copied->parts == doc::Parts::all || copied->parts == doc::Parts::brief; - bool const copyDetails = copied->parts == doc::Parts::all || copied->parts == doc::Parts::description; - Javadoc const& src = *res.javadoc; - if (copyBrief && !javadoc.brief) - { - javadoc.brief = src.brief; - } - if (copyDetails) +void +JavadocFinalizer:: +finalize(Javadoc& javadoc) +{ + finalize(javadoc.blocks); + finalize(javadoc.brief); + finalize(javadoc.returns); + finalize(javadoc.params); + finalize(javadoc.tparams); + finalize(javadoc.exceptions); + finalize(javadoc.sees); + finalize(javadoc.preconditions); + finalize(javadoc.postconditions); + processRelates(javadoc); + copyDetails(javadoc); + removeTempTextNodes(javadoc); + trimBlocks(javadoc); + unindentCodeBlocks(javadoc); +} + +namespace { +bool +referenceCmp( + doc::Reference const& lhs, + doc::Reference const& rhs) { + bool const lhsIsGlobal = lhs.string.starts_with("::"); + bool const rhsIsGlobal = rhs.string.starts_with("::"); + if (lhsIsGlobal != rhsIsGlobal) + { + return lhsIsGlobal < rhsIsGlobal; + } + std::size_t const lhsCount = std::ranges::count(lhs.string, ':'); + std::size_t const rhsCount = std::ranges::count(rhs.string, ':'); + if (lhsCount != rhsCount) + { + return lhsCount < rhsCount; + } + if (lhs.string != rhs.string) + { + return lhs.string < rhs.string; + } + return lhs.id < rhs.id; +} +} + +void +JavadocFinalizer:: +processRelates(Javadoc& javadoc) +{ + if (corpus_.config->autoRelates) + { + setAutoRelates(); + } + + MRDOCS_CHECK_OR(!javadoc.relates.empty()); + + Info const* currentPtr = corpus_.find(current_context_->id); + MRDOCS_ASSERT(currentPtr); + Info const current = *currentPtr; + + if (!current.isFunction()) + { + this->warn( + "{}: `@relates` only allowed for functions", + corpus_.Corpus::qualifiedName(current)); + javadoc.relates.clear(); + return; + } + + for (doc::Reference& ref: javadoc.relates) + { + finalize(ref, true); + Info* relatedPtr = corpus_.find(ref.id); + MRDOCS_CHECK_OR_CONTINUE(relatedPtr); + Info& related = *relatedPtr; + if (!related.javadoc) { - // Copy detail blocks - if (!src.blocks.empty()) - { - blockIt = javadoc.blocks.insert(blockIt, src.blocks.begin(), src.blocks.end()); - blockIt = std::next(blockIt, src.blocks.size()); - } - // Copy returns only if destination is empty - if (javadoc.returns.empty()) - { - javadoc.returns.insert( - javadoc.returns.end(), - src.returns.begin(), - src.returns.end()); - } - // Copy only params that don't exist at the destination - // documentation but that do exist in the destination - // function parameters declaration. - if (current_context_->isFunction()) - { - auto const& FI = dynamic_cast(*current_context_); - for (auto const& srcParam: src.params) - { - if (std::ranges::find_if(javadoc.params, - [&srcParam](doc::Param const& destParam) - { - return srcParam.name == destParam.name; - }) != javadoc.params.end()) - { - // param already exists at the destination, - // so the user attributed a new meaning to it - continue; - } - if (std::ranges::find_if(FI.Params, - [&srcParam](Param const& destParam) - { - return srcParam.name == *destParam.Name; - }) == FI.Params.end()) - { - // param does not exist in the destination function - // so it would be an error there - continue; - } - // Push the new param - javadoc.params.push_back(srcParam); - } - } - // Copy only tparams that don't exist at the destination - // documentation but that do exist in the destination - // template parameters. - TemplateInfo const* destTemplate = visit( - *current_context_, - [](auto& I) -> TemplateInfo const* - { - if constexpr (requires { I.Template; }) - { - if (I.Template) - { - return &*I.Template; - } - } - return nullptr; - }); - if (destTemplate) - { - for (auto const& srcTParam: src.tparams) - { - if (std::ranges::find_if(javadoc.tparams, - [&srcTParam](doc::TParam const& destTParam) - { - return srcTParam.name == destTParam.name; - }) != javadoc.tparams.end()) - { - // tparam already exists at the destination, - // so the user attributed a new meaning to it - continue; - } - if (std::ranges::find_if(destTemplate->Params, - [&srcTParam](Polymorphic const& destTParam) - { - return srcTParam.name == destTParam->Name; - }) == destTemplate->Params.end()) - { - // TParam does not exist in the destination definition - // so it would be an error there - continue; - } - // Push the new param - javadoc.tparams.push_back(srcTParam); - } - } - // exceptions - if (javadoc.exceptions.empty()) - { - bool const isNoExcept = - current_context_->isFunction() ? - dynamic_cast(*current_context_).Noexcept.Kind == NoexceptKind::False : - false; - if (!isNoExcept) - { - javadoc.exceptions.insert( - javadoc.exceptions.end(), - src.exceptions.begin(), - src.exceptions.end()); - } - } - // sees - if (javadoc.sees.empty()) - { - javadoc.sees.insert( - javadoc.sees.end(), - src.sees.begin(), - src.sees.end()); - } - // preconditions - if (javadoc.preconditions.empty()) - { - javadoc.preconditions.insert( - javadoc.preconditions.end(), - src.preconditions.begin(), - src.preconditions.end()); - } - // postconditions - if (javadoc.postconditions.empty()) - { - javadoc.postconditions.insert( - javadoc.postconditions.end(), - src.postconditions.begin(), - src.postconditions.end()); - } - continue; + related.javadoc.emplace(); } - // Erasing the paragraph could make the iterator == end() - if (blockIt != javadoc.blocks.end()) + if (std::ranges::none_of( + related.javadoc->related, + [this](doc::Reference const& otherRef) { + return otherRef.id == current_context_->id; + })) { - ++blockIt; + std::string currentName = corpus_.Corpus::qualifiedName(current, relatedPtr->Parent); + doc::Reference relatedRef(std::move(currentName)); + relatedRef.id = current_context_->id; + // Insert in order by name + auto const it = std::ranges::lower_bound( + related.javadoc->related, + relatedRef, + referenceCmp); + related.javadoc->related.insert(it, std::move(relatedRef)); } } + + // Erase anything in the javadoc without a valid id + std::erase_if(javadoc.relates, [](doc::Reference const& ref) { + return !ref.id; + }); +} + +void +JavadocFinalizer:: +removeTempTextNodes(Javadoc& javadoc) +{ + removeTempTextNodes(javadoc.blocks); + if (javadoc.brief) + { + removeTempTextNodes(*javadoc.brief); + } + removeTempTextNodes(javadoc.returns); + removeTempTextNodes(javadoc.params); + removeTempTextNodes(javadoc.tparams); + removeTempTextNodes(javadoc.exceptions); + removeTempTextNodes(javadoc.sees); + removeTempTextNodes(javadoc.preconditions); + removeTempTextNodes(javadoc.postconditions); } void JavadocFinalizer:: -setAutoBrief(Javadoc& javadoc) +removeTempTextNodes(std::vector>& blocks) { - MRDOCS_CHECK_OR(corpus_.config->autoBrief); - MRDOCS_CHECK_OR(!javadoc.brief); - MRDOCS_CHECK_OR(!javadoc.blocks.empty()); - for (auto it = javadoc.blocks.begin(); it != javadoc.blocks.end();) + for (auto& block: blocks) { - if (auto& block = *it; - block->Kind == doc::NodeKind::paragraph || - block->Kind == doc::NodeKind::details) + removeTempTextNodes(*block); + } + // Erase all blocks of zero elements + std::erase_if(blocks, [](Polymorphic const& block) { + if (block->Kind == doc::NodeKind::unordered_list) { - auto& para = dynamic_cast(*block); - if (para.children.empty()) - { - ++it; - continue; - } - javadoc.brief.emplace(); - javadoc.brief->children = para.children; - it = javadoc.blocks.erase(it); - return; + return get(block).items.empty(); } - ++it; - } + if (block->Kind == doc::NodeKind::heading) + { + return get(block).string.empty(); + } + return block->children.empty(); + }); +} + +void +JavadocFinalizer:: +removeTempTextNodes(doc::Block& block) +{ + std::erase_if(block.children, [](Polymorphic const& child) { + return is_one_of( + child->Kind, + { doc::NodeKind::copy_details }); + }); } void @@ -826,212 +1026,487 @@ trimBlock(doc::Block& block) return startsWithOneOf(str, whitespace_chars); }; - // The first children are ltrimmed as one - while (!block.children.empty()) + // The first children are ltrimmed as one + while (!block.children.empty()) + { + auto& first = block.children.front()->string; + if (startsWithSpace(first)) + { + first = ltrim(first); + } + if (first.empty()) + { + // "pop_front" + block.children.erase(block.children.begin()); + } + else + { + break; + } + } + + // The last children are rtrimmed as one + while (!block.children.empty()) + { + auto& last = block.children.back()->string; + if (endsWithSpace(last)) + { + last = rtrim(last); + } + if (last.empty()) + { + block.children.pop_back(); + } + else + { + break; + } + } + + // Like in HTML, multiple whitespaces (spaces, tabs, and newlines) + // between and within child nodes are collapsed into a single space. + if (!block.children.empty()) + { + for ( + auto it = block.children.begin() + 1; + it != block.children.end(); + ++it) + { + auto& child = *it; + auto& prev = *std::prev(it); + if (endsWithSpace(prev->string) && startsWithSpace(child->string)) + { + // The first visible space character is maintained. + // All others are removed. + prev->string = rtrim(prev->string); + prev->string.push_back(' '); + child->string = ltrim(child->string); + } + } + } + + // Like in HTML, multiple whitespaces (spaces, tabs, and newlines) + // within child nodes are collapsed into a single space. + for (auto& child: block.children) + { + auto& str = child->string; + for (std::size_t i = 0; i < str.size();) + { + if (contains(whitespace_chars, str[i])) + { + std::size_t const runStart = i; + std::size_t runEnd = i + 1; + while ( + runEnd < str.size() && + contains(whitespace_chars, str[runEnd])) + { + ++runEnd; + } + if (runEnd > runStart + 1) + { + std::size_t const runSize = runEnd - runStart; + str.erase(runStart + 1, runSize - 1); + str[runStart] = ' '; + } + i = runEnd; + } + else + { + ++i; + } + } + } +} + +void +JavadocFinalizer:: +unindentCodeBlocks(Javadoc& javadoc) +{ + unindentCodeBlocks(javadoc.blocks); + if (javadoc.brief) + { + unindentCodeBlocks(*javadoc.brief); + } + unindentCodeBlocks(javadoc.returns); + unindentCodeBlocks(javadoc.params); + unindentCodeBlocks(javadoc.tparams); + unindentCodeBlocks(javadoc.exceptions); + unindentCodeBlocks(javadoc.sees); + unindentCodeBlocks(javadoc.preconditions); + unindentCodeBlocks(javadoc.postconditions); +} + +void +JavadocFinalizer:: +unindentCodeBlocks(std::vector>& blocks) +{ + for (auto& block: blocks) + { + if (block->Kind == doc::NodeKind::code) + { + unindentCodeBlocks(*block); + } + } +} + +void +JavadocFinalizer:: +unindentCodeBlocks(doc::Block& block) +{ + MRDOCS_CHECK_OR(block.Kind == doc::NodeKind::code); + MRDOCS_CHECK_OR(!block.children.empty()); + + // Determine the left margin + std::size_t leftMargin = std::numeric_limits::max(); + for (auto& pText: block.children) + { + auto& text = dynamic_cast(*pText); + if (text.string.empty()) + { + continue; + } + std::size_t const margin = text.string.find_first_not_of(" \t"); + if (margin == std::string::npos) + { + continue; + } + leftMargin = std::min(leftMargin, margin); + } + + MRDOCS_CHECK_OR(leftMargin != std::numeric_limits::max()); + + // Remove the left margin + for (auto& pText: block.children) + { + auto& text = dynamic_cast(*pText); + if (text.string.size() < leftMargin) + { + continue; + } + text.string = text.string.substr(leftMargin); + } +} + +namespace { +void +pushAllDerivedClasses( + RecordInfo const* record, + SmallVector& relatedRecordsOrEnums, + CorpusImpl& corpus) +{ + for (auto& derivedId : record->Derived) + { + Info* derivedPtr = corpus.find(derivedId); + MRDOCS_CHECK_OR_CONTINUE(derivedPtr); + MRDOCS_CHECK_OR_CONTINUE(derivedPtr->Extraction == ExtractionMode::Regular); + auto derived = dynamic_cast(derivedPtr); + MRDOCS_CHECK_OR_CONTINUE(derived); + relatedRecordsOrEnums.push_back(derived); + // Recursively get derived classes of the derived class + pushAllDerivedClasses(derived, relatedRecordsOrEnums, corpus); + } +} +} + +void +JavadocFinalizer:: +setAutoRelates() +{ + MRDOCS_ASSERT(current_context_); + MRDOCS_CHECK_OR(current_context_->Extraction == ExtractionMode::Regular); + MRDOCS_CHECK_OR(current_context_->isFunction()); + MRDOCS_CHECK_OR(current_context_->javadoc); + auto& I = dynamic_cast(*current_context_); + MRDOCS_CHECK_OR(!I.IsRecordMethod); + auto* parentPtr = corpus_.find(I.Parent); + MRDOCS_CHECK_OR(parentPtr); + MRDOCS_CHECK_OR(parentPtr->isNamespace()); + + auto toRecordOrEnum = [&](Polymorphic const& type) -> Info* { + MRDOCS_CHECK_OR(type, nullptr); + auto& innermost = innermostType(type); + MRDOCS_CHECK_OR(innermost, nullptr); + MRDOCS_CHECK_OR(innermost->isNamed(), nullptr); + auto const& namedType = dynamic_cast(*innermost); + MRDOCS_CHECK_OR(namedType.Name, nullptr); + SymbolID const namedSymbolID = namedType.Name->id; + MRDOCS_CHECK_OR(namedSymbolID != SymbolID::invalid, nullptr); + Info* infoPtr = corpus_.find(namedSymbolID); + MRDOCS_CHECK_OR(infoPtr, nullptr); + MRDOCS_CHECK_OR( + infoPtr->isRecord() || + infoPtr->isEnum(), nullptr); + return infoPtr; + }; + + SmallVector relatedRecordsOrEnums; + + // 1) Inner type of the first parameter + [&] { + MRDOCS_CHECK_OR(!I.Params.empty()); + auto* firstParamInfo = toRecordOrEnum(I.Params.front().Type); + MRDOCS_CHECK_OR(firstParamInfo); + if (firstParamInfo->Extraction == ExtractionMode::Regular) + { + relatedRecordsOrEnums.push_back(firstParamInfo); + } + // 2) If the type is a reference or a pointer, derived classes + // of this inner type are also valid related records + MRDOCS_CHECK_OR(firstParamInfo->isRecord()); + auto const* firstParamRecord = dynamic_cast(firstParamInfo); + MRDOCS_CHECK_OR( + I.Params.front().Type->isLValueReference() || + I.Params.front().Type->isRValueReference() || + I.Params.front().Type->isPointer()); + // Get all transitively derived classes of firstParamRecord + pushAllDerivedClasses(firstParamRecord, relatedRecordsOrEnums, corpus_); + }(); + + // 3) The return type of the function + if (auto* returnTypeInfo = toRecordOrEnum(I.ReturnType)) + { + if (returnTypeInfo->Extraction == ExtractionMode::Regular) + { + relatedRecordsOrEnums.push_back(returnTypeInfo); + } + // 4) If the return type is a template specialization, + // and the template parameters are records, then + // each template parameter is also a related record + [&] { + MRDOCS_CHECK_OR(I.ReturnType); + MRDOCS_CHECK_OR(I.ReturnType->isNamed()); + auto& NTI = get(I.ReturnType); + MRDOCS_CHECK_OR(NTI.Name); + MRDOCS_CHECK_OR(NTI.Name->isSpecialization()); + auto const& NTIS = get(NTI.Name); + MRDOCS_CHECK_OR(!NTIS.TemplateArgs.empty()); + Polymorphic const& firstArg = NTIS.TemplateArgs.front(); + MRDOCS_CHECK_OR(firstArg->isType()); + auto const& typeArg = get(firstArg); + if (auto* argInfo = toRecordOrEnum(typeArg.Type)) + { + if (argInfo->Extraction == ExtractionMode::Regular) + { + relatedRecordsOrEnums.push_back(argInfo); + } + } + }(); + } + + // Remove duplicates from relatedRecordsOrEnums + std::ranges::sort(relatedRecordsOrEnums); + relatedRecordsOrEnums.erase( + std::ranges::unique(relatedRecordsOrEnums).begin(), + relatedRecordsOrEnums.end()); + + // Insert the records with valid ids into the javadoc relates section + std::size_t const prevRelatesSize = I.javadoc->relates.size(); + for (Info const* relatedRecordOrEnumPtr : relatedRecordsOrEnums) { - auto& first = block.children.front()->string; - if (startsWithSpace(first)) - { - first = ltrim(first); - } - if (first.empty()) + MRDOCS_CHECK_OR_CONTINUE(relatedRecordOrEnumPtr); + MRDOCS_ASSERT(I.javadoc); + Info const& recordOrEnum = *relatedRecordOrEnumPtr; + MRDOCS_CHECK_OR_CONTINUE(recordOrEnum.Extraction == ExtractionMode::Regular); + doc::Reference ref(recordOrEnum.Name); + ref.id = recordOrEnum.id; + + // Check if already listed as friend + if (auto* record = dynamic_cast(relatedRecordOrEnumPtr)) { - // "pop_front" - block.children.erase(block.children.begin()); + auto fromFriendIdToTypeID = [&](SymbolID const& id) -> SymbolID { + Info* friendInfo = corpus_.find(id); + MRDOCS_CHECK_OR(friendInfo, SymbolID::invalid); + auto const friendPtr = dynamic_cast(friendInfo); + MRDOCS_CHECK_OR(friendPtr, SymbolID::invalid); + return friendPtr->FriendSymbol; + }; + using std::views::transform; + if (contains(transform(record->Interface.Public.Friends, fromFriendIdToTypeID), I.id)) + { + // Already listed as a public friend + continue; + } } - else + + // Ensure no duplicates + if (std::ranges::none_of( + I.javadoc->relates, + [&ref](doc::Reference const& otherRef) { + return otherRef.string == ref.string || otherRef.id == ref.id; + })) { - break; + // Insert in order by name + auto const it = std::ranges::lower_bound( + I.javadoc->relates.begin() + prevRelatesSize, + I.javadoc->relates.end(), + ref, + referenceCmp); + I.javadoc->relates.insert(it, std::move(ref)); } } +} - // The last children are rtrimmed as one - while (!block.children.empty()) +void +JavadocFinalizer:: +copyDetails(Javadoc& javadoc) +{ + for (auto blockIt = javadoc.blocks.begin(); blockIt != javadoc.blocks.end();) { - auto& last = block.children.back()->string; - if (endsWithSpace(last)) + // Get paragraph + auto& block = *blockIt; + if (block->Kind != doc::NodeKind::paragraph && + block->Kind != doc::NodeKind::details) { - last = rtrim(last); + ++blockIt; + continue; } - if (last.empty()) + auto& para = dynamic_cast(*block); + if (para.children.empty()) { - block.children.pop_back(); + ++blockIt; + continue; } - else + + // Find copydetails command + std::optional copied; + for (auto textIt = para.children.begin(); textIt != para.children.end();) { + // Find copydoc command + auto& text = *textIt; + if (text->Kind != doc::NodeKind::copy_details) + { + ++textIt; + continue; + } + // Copy reference + copied = dynamic_cast(*text); + + // Remove copied node from the text + /* it2 = */ para.children.erase(textIt); break; } - } - // Like in HTML, multiple whitespaces (spaces, tabs, and newlines) - // between and within child nodes are collapsed into a single space. - for ( - auto it = block.children.begin() + 1; - it != block.children.end(); - ++it) - { - auto& child = *it; - auto& prev = *std::prev(it); - if (endsWithSpace(prev->string) && startsWithSpace(child->string)) + // Remove leading children from the paragraph that are + // either empty or only white spaces. We also ltrim + // the first child with content. + while (!para.children.empty()) { - // The first visible space character is maintained. - // All others are removed. - prev->string = rtrim(prev->string); - prev->string.push_back(' '); - child->string = ltrim(child->string); + if (para.children.front()->string.find_first_not_of(" \t\n\v\f\r") == std::string::npos) + { + para.children.erase(para.children.begin()); + } + else + { + para.children.front()->string = ltrim(para.children.front()->string); + break; + } } - } - // Like in HTML, multiple whitespaces (spaces, tabs, and newlines) - // within child nodes are collapsed into a single space. - for (auto& child: block.children) - { - auto& str = child->string; - for (std::size_t i = 0; i < str.size();) + // Remove trailing children from the paragraph that are + // either empty or only white spaces. We also rtrim + // the last child with content. + while (!para.children.empty()) { - if (contains(whitespace_chars, str[i])) + if (para.children.back()->string.find_first_not_of(" \t\n\v\f\r") == std::string::npos) { - std::size_t const runStart = i; - std::size_t runEnd = i + 1; - while ( - runEnd < str.size() && - contains(whitespace_chars, str[runEnd])) - { - ++runEnd; - } - if (runEnd > runStart + 1) - { - std::size_t const runSize = runEnd - runStart; - str.erase(runStart + 1, runSize - 1); - str[runStart] = ' '; - } - i = runEnd; + para.children.pop_back(); } else { - ++i; + para.children.back()->string = rtrim(para.children.back()->string); + break; } } - } -} -void -JavadocFinalizer:: -removeTempTextNodes(Javadoc& javadoc) -{ - removeTempTextNodes(javadoc.blocks); - if (javadoc.brief) - { - removeTempTextNodes(*javadoc.brief); - } - removeTempTextNodes(javadoc.returns); - removeTempTextNodes(javadoc.params); - removeTempTextNodes(javadoc.tparams); - removeTempTextNodes(javadoc.exceptions); - removeTempTextNodes(javadoc.sees); - removeTempTextNodes(javadoc.preconditions); - removeTempTextNodes(javadoc.postconditions); -} + // Remove empty completely empty children from the paragraph + std::erase_if(para.children, [](Polymorphic const& child) { + return child->string.empty(); + }); -void -JavadocFinalizer:: -removeTempTextNodes(std::vector>& blocks) -{ - for (auto& block: blocks) - { - removeTempTextNodes(*block); - } - // Erase all blocks of zero elements - std::erase_if(blocks, [](Polymorphic const& block) { - if (block->Kind == doc::NodeKind::unordered_list) - { - return get(block).items.empty(); - } - if (block->Kind == doc::NodeKind::heading) + // Merge consecutive text nodes that have exactly the same terminal kind + for (auto textIt = para.children.begin(); textIt != para.children.end();) { - return get(block).string.empty(); + auto& text = *textIt; + if (textIt != para.children.begin()) + { + if (auto& prev = *std::prev(textIt); + prev->Kind == text->Kind) + { + prev->string += text->string; + textIt = para.children.erase(textIt); + continue; + } + } + ++textIt; } - return block->children.empty(); - }); -} - -void -JavadocFinalizer:: -removeTempTextNodes(doc::Block& block) -{ - std::erase_if(block.children, [](Polymorphic const& child) { - return is_one_of( - child->Kind, - { doc::NodeKind::copied }); - }); -} - -void -JavadocFinalizer:: -unindentCodeBlocks(Javadoc& javadoc) -{ - unindentCodeBlocks(javadoc.blocks); - if (javadoc.brief) - { - unindentCodeBlocks(*javadoc.brief); - } - unindentCodeBlocks(javadoc.returns); - unindentCodeBlocks(javadoc.params); - unindentCodeBlocks(javadoc.tparams); - unindentCodeBlocks(javadoc.exceptions); - unindentCodeBlocks(javadoc.sees); - unindentCodeBlocks(javadoc.preconditions); - unindentCodeBlocks(javadoc.postconditions); -} -void -JavadocFinalizer:: -unindentCodeBlocks(std::vector>& blocks) -{ - for (auto& block: blocks) - { - if (block->Kind == doc::NodeKind::code) + // Remove the entire paragraph block from the javadoc if it is empty + if (para.empty()) { - unindentCodeBlocks(*block); + blockIt = javadoc.blocks.erase(blockIt); + MRDOCS_CHECK_OR_CONTINUE(copied); } - } -} - -void -JavadocFinalizer:: -unindentCodeBlocks(doc::Block& block) -{ - MRDOCS_CHECK_OR(block.Kind == doc::NodeKind::code); - MRDOCS_CHECK_OR(!block.children.empty()); - // Determine the left margin - std::size_t leftMargin = std::numeric_limits::max(); - for (auto& pText: block.children) - { - auto& text = dynamic_cast(*pText); - if (text.string.empty()) + // Nothing to copy: continue to the next block + if (!copied) { + ++blockIt; continue; } - std::size_t const margin = text.string.find_first_not_of(" \t"); - if (margin == std::string::npos) + + // Find the node to copy from + auto resRef = corpus_.lookup(current_context_->id, copied->string); + if (!resRef) { + if (corpus_.config->warnings && + corpus_.config->warnBrokenRef && + !refWarned_.contains({copied->string, current_context_->Name})) + { + this->warn( + "{}: Failed to copy documentation from '{}' (symbol not found)\n" + " {}", + corpus_.Corpus::qualifiedName(*current_context_), + copied->string, + resRef.error().reason()); + } continue; } - leftMargin = std::min(leftMargin, margin); - } - MRDOCS_CHECK_OR(leftMargin != std::numeric_limits::max()); + // Ensure the source node is finalized + Info const& res = *resRef; + finalizeJavadoc(const_cast(res)); - // Remove the left margin - for (auto& pText: block.children) - { - auto& text = dynamic_cast(*pText); - if (text.string.size() < leftMargin) + // Check if there's any documentation details to copy + if (!res.javadoc) { + if (corpus_.config->warnings && + corpus_.config->warnBrokenRef && + !refWarned_.contains({copied->string, current_context_->Name})) + { + auto resPrimaryLoc = getPrimaryLocation(res); + this->warn( + "{}: Failed to copy documentation from {} '{}' (no documentation available).\n" + " No documentation available.\n" + " {}:{}\n" + " Note: No documentation available for '{}'.", + corpus_.Corpus::qualifiedName(*current_context_), + toString(res.Kind), + copied->string, + resPrimaryLoc->FullPath, + resPrimaryLoc->LineNumber, + corpus_.Corpus::qualifiedName(res)); + } continue; } - text.string = text.string.substr(leftMargin); + + // Copy detail blocks from source to destination to + // the same position in the destination + Javadoc const& src = *res.javadoc; + if (!src.blocks.empty()) + { + blockIt = javadoc.blocks.insert(blockIt, src.blocks.begin(), src.blocks.end()); + blockIt += src.blocks.size(); + } } } @@ -1167,477 +1642,6 @@ checkExists(SymbolID const& id) const MRDOCS_ASSERT(corpus_.info_.contains(id)); } -namespace { -template -bool -populateOverloadsBriefIfAllSameBrief(OverloadsInfo& I, Range&& functionsWithBrief) -{ - auto first = *functionsWithBrief.begin(); - doc::Brief const& firstBrief = *first.javadoc->brief; - if (auto otherFunctions = std::views::drop(functionsWithBrief, 1); - std::ranges::all_of(otherFunctions, [&](FunctionInfo const& otherFunction) - { - doc::Brief const& otherBrief = *otherFunction.javadoc->brief; - return otherBrief == firstBrief; - })) - { - I.javadoc->brief = firstBrief; - return true; - } - return false; -} - -void -setBriefString(std::optional& brief, std::string_view str) { - brief.emplace(); - brief->children.emplace_back(MakePolymorphic(std::string(str))); -} - -bool -populateOverloadsFromClass(OverloadsInfo& I) -{ - switch (I.Class) - { - case FunctionClass::Normal: - return false; - case FunctionClass::Constructor: - { - setBriefString(I.javadoc->brief, "Constructors"); - return true; - } - case FunctionClass::Conversion: - { - setBriefString(I.javadoc->brief, "Conversion operators"); - return true; - } - case FunctionClass::Destructor: - default: - MRDOCS_UNREACHABLE(); - } -} - -template -bool -populateOverloadsFromOperator(OverloadsInfo& I, Range&& functions) -{ - if (I.OverloadedOperator == OperatorKind::None) - { - return false; - } - // An array of pairs describing the operator kind and the - // default brief string for that operator kind. - struct OperatorBrief { - OperatorKind kind = OperatorKind::None; - std::string_view brief; - std::string_view binaryBrief; - constexpr - OperatorBrief( - OperatorKind kind, - std::string_view brief, - std::string_view binaryBrief = "") - : kind(kind) - , brief(brief) - , binaryBrief(binaryBrief) {} - }; - static constexpr OperatorBrief operatorBriefs[] = { - {OperatorKind::Equal, "Assignment operators"}, - {OperatorKind::Star, "Dereference operators", "Multiplication operators"}, - {OperatorKind::Arrow, "Member access operators"}, - {OperatorKind::Exclaim, "Negation operators"}, - {OperatorKind::EqualEqual, "Equality operators"}, - {OperatorKind::ExclaimEqual, "Inequality operators"}, - {OperatorKind::Less, "Less-than operators"}, - {OperatorKind::LessEqual, "Less-than-or-equal operators"}, - {OperatorKind::Greater, "Greater-than operators"}, - {OperatorKind::GreaterEqual, "Greater-than-or-equal operators"}, - {OperatorKind::Spaceship, "Three-way comparison operators"}, - {OperatorKind::AmpAmp, "Conjunction operators"}, - {OperatorKind::PipePipe, "Disjunction operators"}, - {OperatorKind::PlusPlus, "Increment operators"}, - {OperatorKind::MinusMinus, "Decrement operators"}, - {OperatorKind::Comma, "Comma operators"}, - {OperatorKind::ArrowStar, "Pointer-to-member operators"}, - {OperatorKind::Call, "Function call operators"}, - {OperatorKind::Subscript, "Subscript operators"}, - {OperatorKind::Conditional, "Ternary operators"}, - {OperatorKind::Coawait, "Coawait operators"}, - {OperatorKind::New, "New operators"}, - {OperatorKind::Delete, "Delete operators"}, - {OperatorKind::ArrayNew, "New array operators"}, - {OperatorKind::ArrayDelete, "Delete array operators"}, - {OperatorKind::Plus, "Unary plus operators", "Addition operators"}, - {OperatorKind::Minus, "Unary minus operators", "Subtraction operators"}, - {OperatorKind::Slash, "Division operators"}, - {OperatorKind::Percent, "Modulus operators"}, - {OperatorKind::Pipe, "Bitwise disjunction operators"}, - {OperatorKind::Caret, "Bitwise exclusive-or operators"}, - {OperatorKind::Tilde, "Bitwise negation operators"}, - {OperatorKind::PlusEqual, "Addition assignment operators"}, - {OperatorKind::MinusEqual, "Subtraction assignment operators"}, - {OperatorKind::StarEqual, "Multiplication assignment operators"}, - {OperatorKind::SlashEqual, "Division assignment operators"}, - {OperatorKind::PercentEqual, "Modulus assignment operators"}, - {OperatorKind::Amp, "Address-of operators", "Bitwise conjunction operators"}, - {OperatorKind::AmpEqual, "Bitwise conjunction assignment operators"}, - {OperatorKind::PipeEqual, "Bitwise disjunction assignment operators"}, - {OperatorKind::CaretEqual, "Bitwise exclusive-or assignment operators"}, - {OperatorKind::LessLess, "Left shift operators"}, - {OperatorKind::GreaterGreater, "Right shift operators"}, - {OperatorKind::LessLessEqual, "Left shift assignment operators"}, - {OperatorKind::GreaterGreaterEqual, "Right shift assignment operators"} - }; - for (auto const& [kind, brief, binaryBrief]: operatorBriefs) - { - MRDOCS_CHECK_OR_CONTINUE(I.OverloadedOperator == kind); - - // The name for operator<< depends on the parameter types - if (kind == OperatorKind::LessLess) - { - // Check if all functions are Stream Operators: - // 1) Non-member function - // 2) First param is mutable reference - // 3) Return type is mutable reference of same type as first param - if (std::ranges::all_of(functions, - [&](FunctionInfo const& function) - { - MRDOCS_CHECK_OR(!function.IsRecordMethod, false); - MRDOCS_CHECK_OR(function.Params.size() == 2, false); - // Check first param is mutable left reference - auto& firstParam = function.Params[0]; - MRDOCS_CHECK_OR(firstParam, false); - auto& firstQualType = firstParam.Type; - MRDOCS_CHECK_OR(firstQualType, false); - MRDOCS_CHECK_OR(firstQualType->isLValueReference(), false); - auto& firstNamedType = get(firstQualType).PointeeType; - MRDOCS_CHECK_OR(firstNamedType, false); - MRDOCS_CHECK_OR(firstNamedType->isNamed(), false); - // Check return type - return firstQualType == function.ReturnType; - })) - { - setBriefString(I.javadoc->brief, "Stream insertion operators"); - } - else - { - // Regular brief as more generic left shift operator otherwise - setBriefString(I.javadoc->brief, brief); - } - return true; - } - - if (binaryBrief.empty()) - { - setBriefString(I.javadoc->brief, brief); - return true; - } - - if (std::ranges::all_of(functions, - [&](FunctionInfo const& function) - { - return (function.Params.size() + function.IsRecordMethod) == 2; - })) - { - setBriefString(I.javadoc->brief, binaryBrief); - return true; - } - - if (std::ranges::all_of(functions, - [&](FunctionInfo const& function) - { - return (function.Params.size() + function.IsRecordMethod) == 1; - })) - { - setBriefString(I.javadoc->brief, brief); - return true; - } - return false; - } - return false; -} - -bool -populateOverloadsFromFunctionName(OverloadsInfo& I) -{ - std::string name = I.Name; - if (name.empty() && - I.OverloadedOperator != OperatorKind::None) - { - name = getOperatorName(I.OverloadedOperator, true); - } - if (name.empty()) - { - return false; - } - I.javadoc->brief.emplace(); - I.javadoc->brief->children.emplace_back(MakePolymorphic(std::string(name), doc::Style::mono)); - I.javadoc->brief->children.emplace_back(MakePolymorphic(std::string(" overloads"))); - return true; -} - -template -void -populateOverloadsBrief(OverloadsInfo& I, Range&& functions) -{ - auto functionsWithBrief = std::views::filter(functions, - [](FunctionInfo const& function) - { - return - function.javadoc && - function.javadoc->brief && - !function.javadoc->brief->empty(); - }); - if (std::ranges::empty(functionsWithBrief)) - { - return; - } - MRDOCS_CHECK_OR(!populateOverloadsBriefIfAllSameBrief(I, functionsWithBrief)); - MRDOCS_CHECK_OR(!populateOverloadsFromClass(I)); - MRDOCS_CHECK_OR(!populateOverloadsFromOperator(I, functions)); - MRDOCS_CHECK_OR(!populateOverloadsFromFunctionName(I)); -} - -template -void -populateOverloadsReturns(OverloadsInfo& I, Range&& functions) { - auto functionReturns = functions | - std::views::filter([](FunctionInfo const& function) - { - return function.javadoc && !function.javadoc->returns.empty(); - }) | - std::views::transform([](FunctionInfo const& function) - { - return function.javadoc->returns; - }) | - std::views::join; - for (doc::Returns const& functionReturn: functionReturns) - { - auto sameIt = std::ranges::find_if( - I.javadoc->returns, - [&functionReturn](doc::Returns const& overloadReturns) - { - return overloadReturns == functionReturn; - }); - if (sameIt == I.javadoc->returns.end()) - { - I.javadoc->returns.push_back(functionReturn); - } - } -} - -template -void -populateOverloadsParams(OverloadsInfo& I, Range& functions) { - auto functionParams = functions | - std::views::filter([](FunctionInfo const& function) - { - return function.javadoc && !function.javadoc->params.empty(); - }) | - std::views::transform([](FunctionInfo const& function) - { - return function.javadoc->params; - }) | - std::views::join; - for (doc::Param const& functionParam: functionParams) - { - auto sameIt = std::ranges::find_if( - I.javadoc->params, - [&functionParam](doc::Param const& overloadParam) - { - return overloadParam.name == functionParam.name; - }); - if (sameIt == I.javadoc->params.end()) - { - I.javadoc->params.push_back(functionParam); - } - } -} - -template -void -populateOverloadsTParams(OverloadsInfo& I, Range& functions) { - auto functionTParams = functions | - std::views::filter([](FunctionInfo const& function) - { - return function.javadoc && !function.javadoc->tparams.empty(); - }) | - std::views::transform([](FunctionInfo const& function) - { - return function.javadoc->tparams; - }) | - std::views::join; - for (doc::TParam const& functionTParam: functionTParams) - { - auto sameIt = std::ranges::find_if( - I.javadoc->tparams, - [&functionTParam](doc::TParam const& overloadTParam) - { - return overloadTParam.name == functionTParam.name; - }); - if (sameIt == I.javadoc->tparams.end()) - { - I.javadoc->tparams.push_back(functionTParam); - } - } -} - -template -void -populateOverloadsExceptions(OverloadsInfo& I, Range& functions) { - auto functionExceptions = functions | - std::views::filter([](FunctionInfo const& function) - { - return function.javadoc && !function.javadoc->exceptions.empty(); - }) | - std::views::transform([](FunctionInfo const& function) - { - return function.javadoc->exceptions; - }) | - std::views::join; - for (doc::Throws const& functionException: functionExceptions) - { - auto sameIt = std::ranges::find_if( - I.javadoc->exceptions, - [&functionException](doc::Throws const& overloadException) - { - return overloadException.exception.string == functionException.exception.string; - }); - if (sameIt == I.javadoc->exceptions.end()) - { - I.javadoc->exceptions.push_back(functionException); - } - } -} - -template -void -populateOverloadsSees(OverloadsInfo& I, Range& functions) { - auto functionSees = functions | - std::views::filter([](FunctionInfo const& function) - { - return function.javadoc && !function.javadoc->sees.empty(); - }) | - std::views::transform([](FunctionInfo const& function) - { - return function.javadoc->sees; - }) | - std::views::join; - for (doc::See const& functionSee: functionSees) - { - auto sameIt = std::ranges::find_if( - I.javadoc->sees, - [&functionSee](doc::See const& overloadSee) - { - return overloadSee.children == functionSee.children; - }); - if (sameIt == I.javadoc->sees.end()) - { - I.javadoc->sees.push_back(functionSee); - } - } -} - -template -void -populateOverloadsPreconditions(OverloadsInfo& I, Range& functions) { - auto functionsPres = functions | - std::views::filter([](FunctionInfo const& function) - { - return function.javadoc && !function.javadoc->preconditions.empty(); - }) | - std::views::transform([](FunctionInfo const& function) - { - return function.javadoc->preconditions; - }) | - std::views::join; - for (doc::Precondition const& functionPre: functionsPres) - { - auto sameIt = std::ranges::find_if( - I.javadoc->preconditions, - [&functionPre](doc::Precondition const& overloadPre) - { - return overloadPre.children == functionPre.children; - }); - if (sameIt == I.javadoc->preconditions.end()) - { - I.javadoc->preconditions.push_back(functionPre); - } - } -} - -template -void -populateOverloadsPostconditions(OverloadsInfo& I, Range& functions) { - auto functionsPosts = functions | - std::views::filter([](FunctionInfo const& function) - { - return function.javadoc && !function.javadoc->postconditions.empty(); - }) | - std::views::transform([](FunctionInfo const& function) - { - return function.javadoc->postconditions; - }) | - std::views::join; - for (doc::Postcondition const& functionPost: functionsPosts) - { - auto sameIt = std::ranges::find_if( - I.javadoc->postconditions, - [&functionPost](doc::Postcondition const& overloadPost) - { - return overloadPost.children == functionPost.children; - }); - if (sameIt == I.javadoc->postconditions.end()) - { - I.javadoc->postconditions.push_back(functionPost); - } - } -} -} // (anon) - - -void -JavadocFinalizer:: -populateOverloadJavadocs(OverloadsInfo& I) -{ - // Create a view all Info members of I - auto functions = - I.Members | - std::views::transform([&](SymbolID const& id) - { - return corpus_.find(id); - }) | - std::views::filter([](Info const* infoPtr) - { - return infoPtr != nullptr && infoPtr->isFunction(); - }) | - std::views::transform([](Info const* infoPtr) -> FunctionInfo const& - { - return *dynamic_cast(infoPtr); - }); - - // Ensure all the members are initialized - for (FunctionInfo const& function: functions) - { - if (!finalized_.contains(&function)) - { - operator()(const_cast(function)); - } - } - - I.javadoc.emplace(); - // blocks: we do not copy javadoc detail blocks because - // it's impossible to guarantee that the details for - // any of the functions make sense for all overloads - populateOverloadsBrief(I, functions); - populateOverloadsReturns(I, functions); - populateOverloadsParams(I, functions); - populateOverloadsTParams(I, functions); - populateOverloadsExceptions(I, functions); - populateOverloadsSees(I, functions); - populateOverloadsPreconditions(I, functions); - populateOverloadsPostconditions(I, functions); -} - - void JavadocFinalizer:: emitWarnings() @@ -1700,31 +1704,6 @@ warnDocErrors() } } -namespace { -/* Get a list of all parameter names in javadoc - - The javadoc parameter names can contain a single parameter or - a list of parameters separated by commas. This function - returns a list of all parameter names in the javadoc. - */ -SmallVector -getJavadocParamNames(Javadoc const& javadoc) -{ - SmallVector result; - for (auto const& javadocParam: javadoc.params) - { - auto const& paramNamesStr = javadocParam.name; - for (auto paramNames = std::views::split(paramNamesStr, ','); - auto const& paramName: paramNames) - { - result.push_back(trim(std::string_view(paramName.begin(), paramName.end()))); - } - } - return result; -} - -} - void JavadocFinalizer:: warnParamErrors(FunctionInfo const& I) diff --git a/src/lib/Metadata/Finalizers/JavadocFinalizer.hpp b/src/lib/Metadata/Finalizers/JavadocFinalizer.hpp index f2412b8cb..5cc9ff1ef 100644 --- a/src/lib/Metadata/Finalizers/JavadocFinalizer.hpp +++ b/src/lib/Metadata/Finalizers/JavadocFinalizer.hpp @@ -46,6 +46,14 @@ class JavadocFinalizer */ std::set finalized_; + /* Info objects whose brief have been finalized + */ + std::set finalized_brief_; + + /* Info objects whose metadata have been finalized + */ + std::set finalized_metadata_; + // A comparison function that sorts locations by: // 1) ascending full path // 2) descending line number @@ -83,124 +91,166 @@ class JavadocFinalizer { } - void - build() - { - for (auto& I : corpus_.info_) - { - MRDOCS_ASSERT(I); - MRDOCS_CHECK_OR_CONTINUE(I->Extraction != ExtractionMode::Dependency); - visit(*I, *this); - } - emitWarnings(); - } + /** Finalize the javadoc for all symbols - void - operator()(Info& I) - { - visit(I, *this); - } + The procedure is composed of steps that resolve + groups of javadoc components for each symbol. - // Finalize javadoc for this info object - template + Groups of components processed later might depend + on components processed earlier. For example, a + function's javadoc might depend on the brief of + the return type and the parameters. Or, the + javadoc of an overload depends on the complete + documentation of the functions it overloads. + */ void - operator()(InfoTy& I); + build(); - // Check and finalize data unrelated to javadoc - template +private: + /** Finalize the brief of a symbol + + The brief is the first paragraph of the documentation + and is used in the index and in the documentation + summary. + */ void - finalizeInfoData(InfoTy& I); + finalizeBrief(Info& I); -private: - // Look for symbol and set the id of a reference + /** Copy the brief from another symbol + + This function copies the brief from another symbol + to the current context. The brief is copied only if + the brief of the current context is empty and + it contains a reference to another symbol created + with \@copybrief or \@copydoc. + */ void - finalize(doc::Reference& ref, bool emitWarning = true); + copyBrief(Javadoc& javadoc); - // Recursively finalize references in a javadoc node + /** Set brief content automatically + + If the brief is empty, this function sets the brief + to the first paragraph of the documentation. + */ void - finalize(doc::Node& node); + setAutoBrief(Javadoc& javadoc) const; + + /** Finalize the metadata copies - // Recursively finalize references in javadoc members + Copy the metadata from other symbols to the current + context whenever the current context contains a + reference to another symbol created with \@copydoc. + */ void - finalize(Javadoc& javadoc); + finalizeMetadataCopies(Info& I); + + /** Populate function javadoc from with missing fields - // Find the ID of "relates" symbols and populate - // the "related" symbol with the inverse. + This function populates the function javadoc with + missing fields of special functions. + */ void - processRelates(Javadoc& javadoc); + populateFunctionJavadoc(FunctionInfo&) const; - // Automatically find related symbols + /** Populate the metadata of overloads + + This function populates the metadata of overloads + with the metadata of the functions it overloads. + */ void - setAutoRelates(); + populateOverloadJavadoc(OverloadsInfo&); - // Copy brief and details to the current context + /** Resolve references in the javadoc + + This function resolves references in the javadoc + of a symbol. The references are resolved by looking + up the symbol in the corpus and setting the id of + the reference. + */ void - copyBriefAndDetails(Javadoc& javadoc); + finalizeJavadoc(Info& I); - // Copy brief from first paragraph + /** Recursively finalize javadoc members + + This function also processes related symbols, + merges consecutive blocks, trims blocks, and + unindents code blocks. + */ void - setAutoBrief(Javadoc& javadoc); + finalize(Javadoc& javadoc); - /* Trim all block childen in the javadoc + /** Resolve \@relates references - The first child is rtrimmed and the last child is ltrimmed. + This function finds the ID of "relates" symbols + and populates the "related" symbol with the inverse. + */ + void + processRelates(Javadoc& javadoc); - Like in HTML, multiple whitespaces (spaces, tabs, and newlines) - between and within child nodes are collapsed into a single space. + /** Remove all temporary text nodes from a block + + The temporary nodes (copied, related, etc...) should + have been processed by the previous steps and should + not be present in the final output. */ void - trimBlocks(Javadoc& javadoc); + removeTempTextNodes(Javadoc& javadoc); - // A range of values derived from blocks + /// A range of values derived from blocks template requires std::derived_from, doc::Block> void - trimBlocks(R&& blocks) + removeTempTextNodes(R&& blocks) { for (auto& block: blocks) { - trimBlock(block); + removeTempTextNodes(block); } } + /// Remove temporary text nodes from a block void - trimBlocks(std::vector>& blocks); + removeTempTextNodes(std::vector>& blocks); + /// Remove temporary text nodes from a block void - trimBlock(doc::Block& block); + removeTempTextNodes(doc::Block& block); + + /** Trim all block childen in the javadoc - /* Remove all temporary text nodes from a block + The first child is rtrimmed and the last child is ltrimmed. - The temporary nodes (copied, related, etc...) should - have been processed by the previous steps and should - not be present in the final output. + Like in HTML, multiple whitespaces (spaces, tabs, and newlines) + between and within child nodes are collapsed into a single space. */ void - removeTempTextNodes(Javadoc& javadoc); + trimBlocks(Javadoc& javadoc); - // A range of values derived from blocks + /// A range of values derived from blocks template requires std::derived_from, doc::Block> void - removeTempTextNodes(R&& blocks) + trimBlocks(R&& blocks) { for (auto& block: blocks) { - removeTempTextNodes(block); + trimBlock(block); } } + /// Trim a block void - removeTempTextNodes(std::vector>& blocks); + trimBlocks(std::vector>& blocks); + /// Trim a block void - removeTempTextNodes(doc::Block& block); + trimBlock(doc::Block& block); - /* Unindent all code blocks in the javadoc - */ + /// Unindent all code blocks in the javadoc void unindentCodeBlocks(Javadoc& javadoc); + /// Unindent code blocks in a range template requires std::derived_from, doc::Block> void @@ -208,16 +258,48 @@ class JavadocFinalizer { for (auto& block: blocks) { - trimBlock(block); + unindentCodeBlocks(block); } } + /// Unindent code blocks in a vector void unindentCodeBlocks(std::vector>& blocks); + /// Unindent a code block void unindentCodeBlocks(doc::Block& block); + /** Check and finalize data unrelated to javadoc + + This checks if all symbol IDs are valid and + removes invalid IDs from the Info data. + */ + template + void + finalizeInfoData(InfoTy& I); + + /** Check the documentation for problems and creates warnings + */ + void + emitWarnings(); + + // Look for symbol and set the id of a reference + void + finalize(doc::Reference& ref, bool emitWarning = true); + + // Recursively finalize references in a javadoc node + void + finalize(doc::Node& node); + + // Automatically find related symbols + void + setAutoRelates(); + + // Copy brief and details to the current context + void + copyDetails(Javadoc& javadoc); + // Set id to invalid if it does not exist void finalize(SymbolID& id); @@ -238,23 +320,23 @@ class JavadocFinalizer void finalize(Param& param); - // Remove invalid ids from BaseInfo members + /// Remove invalid ids from BaseInfo members void finalize(BaseInfo& info); - // Remove invalid ids from TemplateInfo members + /// Remove invalid ids from TemplateInfo members void finalize(TemplateInfo& info); - // Remove invalid ids from TypeInfo members + /// Remove invalid ids from TypeInfo members void finalize(TypeInfo& type); - // Remove invalid ids from NameInfo members + /// Remove invalid ids from NameInfo members void finalize(NameInfo& name); - // Finalize optional and pointer-like members + /// Finalize optional and pointer-like members template void finalize(T&& val) requires @@ -266,7 +348,7 @@ class JavadocFinalizer } } - // Finalize a range of elements + /// Finalize a range of elements template requires std::ranges::input_range void @@ -294,11 +376,7 @@ class JavadocFinalizer })); } - void - populateOverloadJavadocs(OverloadsInfo&); - void - emitWarnings(); template void diff --git a/src/lib/Metadata/Finalizers/SortMembersFinalizer.cpp b/src/lib/Metadata/Finalizers/SortMembersFinalizer.cpp index 0a86574f4..29f35674e 100644 --- a/src/lib/Metadata/Finalizers/SortMembersFinalizer.cpp +++ b/src/lib/Metadata/Finalizers/SortMembersFinalizer.cpp @@ -15,7 +15,7 @@ namespace clang::mrdocs { namespace { -// Comparison function for symbol IDs +// Comparison function by symbol IDs struct SymbolIDCompareFn { CorpusImpl const& corpus_; @@ -151,6 +151,62 @@ struct SymbolIDCompareFn } } + // If both are constructors/assignment with 1 parameter, the copy/move + // constructors come first + if ((lhsClass && *lhsClass == FunctionClass::Constructor && + rhsClass && *rhsClass == FunctionClass::Constructor) || + (lhsOp && *lhsOp == OperatorKind::Equal && + rhsOp && *rhsOp == OperatorKind::Equal)) + { + auto& lhsF = dynamic_cast(lhs); + auto& rhsF = dynamic_cast(rhs); + if (lhsF.Params.size() == 1 && rhsF.Params.size() == 1) + { + auto isCopyOrMoveConstOrAssign = [](FunctionInfo const& I) { + if (I.Params.size() == 1) + { + auto const& param = I.Params[0]; + auto const& paramType = param.Type; + if (!paramType->isLValueReference() + && !paramType->isRValueReference()) + { + return false; + } + auto const& paramRefPointee + = paramType->isLValueReference() ? + get(paramType) + .PointeeType : + get(paramType) + .PointeeType; + if (!paramRefPointee->isNamed()) + { + return false; + } + return paramRefPointee->namedSymbol() == I.Parent; + } + return false; + }; + + bool const lhsIsCopyOrMove = isCopyOrMoveConstOrAssign(lhsF); + bool const rhsIsCopyOrMove = isCopyOrMoveConstOrAssign(rhsF); + if (auto const cmp = lhsIsCopyOrMove <=> rhsIsCopyOrMove; + cmp != 0) + { + return !std::is_lt(cmp); + } + // Ensure move comes after copy + if (lhsIsCopyOrMove && rhsIsCopyOrMove) + { + bool const lhsIsMove = lhsF.Params[0].Type->isRValueReference(); + bool const rhsIsMove = rhsF.Params[0].Type->isRValueReference(); + if (lhsIsMove != rhsIsMove) + { + return !lhsIsMove; + } + } + } + } + if (auto const cmp = lhs.Name <=> rhs.Name; cmp != 0) { return std::is_lt(cmp); diff --git a/src/lib/Metadata/Info/Function.cpp b/src/lib/Metadata/Info/Function.cpp index ecd879832..f3147ab7d 100644 --- a/src/lib/Metadata/Info/Function.cpp +++ b/src/lib/Metadata/Info/Function.cpp @@ -168,9 +168,111 @@ getSafeOperatorName( return full.substr(9); } +std::optional +getOperatorReadableName( + OperatorKind const kind, + int const nParams) +{ + switch (kind) + { + case OperatorKind::Equal: + return "Assignment"; + case OperatorKind::Star: + return nParams != 2 ? "Dereference" : "Multiplication"; + case OperatorKind::Arrow: + return "Member access"; + case OperatorKind::Exclaim: + return "Negation"; + case OperatorKind::EqualEqual: + return "Equality"; + case OperatorKind::ExclaimEqual: + return "Inequality"; + case OperatorKind::Less: + return "Less-than"; + case OperatorKind::LessEqual: + return "Less-than-or-equal"; + case OperatorKind::Greater: + return "Greater-than"; + case OperatorKind::GreaterEqual: + return "Greater-than-or-equal"; + case OperatorKind::Spaceship: + return "Three-way comparison"; + case OperatorKind::AmpAmp: + return "Conjunction"; + case OperatorKind::PipePipe: + return "Disjunction"; + case OperatorKind::PlusPlus: + return "Increment"; + case OperatorKind::MinusMinus: + return "Decrement"; + case OperatorKind::Comma: + return "Comma"; + case OperatorKind::ArrowStar: + return "Pointer-to-member"; + case OperatorKind::Call: + return "Function call"; + case OperatorKind::Subscript: + return "Subscript"; + case OperatorKind::Conditional: + return "Ternary"; + case OperatorKind::Coawait: + return "Coawait"; + case OperatorKind::New: + return "New"; + case OperatorKind::Delete: + return "Delete"; + case OperatorKind::ArrayNew: + return "New array"; + case OperatorKind::ArrayDelete: + return "Delete array"; + case OperatorKind::Plus: + return nParams != 2 ? "Unary plus" : "Addition"; + case OperatorKind::Minus: + return nParams != 2 ? "Unary minus" : "Subtraction"; + case OperatorKind::Slash: + return "Division"; + case OperatorKind::Percent: + return "Modulus"; + case OperatorKind::Pipe: + return "Bitwise disjunction"; + case OperatorKind::Caret: + return "Bitwise exclusive-or"; + case OperatorKind::Tilde: + return "Bitwise negation"; + case OperatorKind::PlusEqual: + return "Addition assignment"; + case OperatorKind::MinusEqual: + return "Subtraction assignment"; + case OperatorKind::StarEqual: + return "Multiplication assignment"; + case OperatorKind::SlashEqual: + return "Division assignment"; + case OperatorKind::PercentEqual: + return "Modulus assignment"; + case OperatorKind::Amp: + return nParams != 2 ? "Address-of" : "Bitwise conjunction"; + case OperatorKind::AmpEqual: + return "Bitwise conjunction assignment"; + case OperatorKind::PipeEqual: + return "Bitwise disjunction assignment"; + case OperatorKind::CaretEqual: + return "Bitwise exclusive-or assignment"; + case OperatorKind::LessLess: + return "Left shift"; + case OperatorKind::GreaterGreater: + return "Right shift"; + case OperatorKind::LessLessEqual: + return "Left shift assignment"; + case OperatorKind::GreaterGreaterEqual: + return "Right shift"; + default: + return std::nullopt; + } + MRDOCS_UNREACHABLE(); +} + dom::String -toString( - FunctionClass kind) noexcept +toString(FunctionClass const kind) noexcept { switch(kind) { diff --git a/src/lib/Metadata/Javadoc.cpp b/src/lib/Metadata/Javadoc.cpp index 9538877ef..cffec9c77 100644 --- a/src/lib/Metadata/Javadoc.cpp +++ b/src/lib/Metadata/Javadoc.cpp @@ -55,7 +55,7 @@ toString(NodeKind kind) noexcept return "tparam"; case NodeKind::reference: return "reference"; - case NodeKind::copied: + case NodeKind::copy_details: return "copied"; case NodeKind::throws: return "throws"; @@ -197,6 +197,15 @@ operator<=>(Polymorphic const& lhs, Polymorphic const& rhs) : std::strong_ordering::greater; } +Paragraph& +Paragraph:: +operator=(std::string_view str) +{ + this->children.clear(); + this->children.emplace_back(MakePolymorphic(std::string(str))); + return *this; +} + } // doc //------------------------------------------------ @@ -211,96 +220,6 @@ Javadoc( { } -doc::Paragraph const* -Javadoc:: -getBrief(Corpus const& corpus) const noexcept -{ - // Brief from a @brief tag - doc::Block const* brief = nullptr; - // The first paragraph promoted to brief - doc::Block const* promoted_brief = nullptr; - // A brief copied from another symbol - doc::Block const* copied_brief = nullptr; - for(auto const& block : blocks) - { - if (!brief && block->Kind == doc::NodeKind::brief) - { - brief = block.operator->(); - } - if (!promoted_brief && block->Kind == doc::NodeKind::paragraph) - { - promoted_brief = block.operator->(); - } - - // if we already have an explicit/copied brief, - // don't check for additional copied briefs - if (brief || copied_brief) - { - continue; - } - - // Look for a @copydoc command - for (auto const& text : block->children) - { - if (text->Kind != doc::NodeKind::copied) - { - continue; - } - if (auto const* copied = dynamic_cast(text.operator->()); - copied->id && - (copied->parts == doc::Parts::all || - copied->parts == doc::Parts::brief)) - { - // Look for the symbol to copy from - if (auto& jd = corpus.get(copied->id).javadoc) - { - copied_brief = jd->getBrief(corpus); - } - } - } - } - // An explicit brief superceeds a copied brief - if (!brief) - { - // No explicit brief: use copied brief - brief = copied_brief; - } - // A copied brief superceeds a promoted brief - if (!brief) - { - // No copied brief: use promoted brief - brief = promoted_brief; - } - return dynamic_cast(brief); -} - -std::vector> const& -Javadoc:: -getDescription(Corpus const& corpus) const noexcept -{ - for (auto const& block : blocks) - { - for(auto const& text : block->children) - { - if (!IsA(text)) - { - continue; - } - if (auto const* copied = dynamic_cast(text.operator->()); - copied->id && - (copied->parts == doc::Parts::all || - copied->parts == doc::Parts::description)) - { - if (auto& jd = corpus.get(copied->id).javadoc) - { - return jd->getDescription(corpus); - } - } - } - } - return blocks; -} - bool Javadoc:: operator==(Javadoc const& other) const noexcept diff --git a/src/lib/Metadata/Specifiers.cpp b/src/lib/Metadata/Specifiers.cpp index 2e3390648..75cefcee3 100644 --- a/src/lib/Metadata/Specifiers.cpp +++ b/src/lib/Metadata/Specifiers.cpp @@ -8,6 +8,7 @@ // Official repository: https://github.com/cppalliance/mrdocs // +#include "mrdocs/Support/Algorithm.hpp" #include namespace clang { @@ -128,5 +129,76 @@ dom::String toString(ReferenceKind kind) noexcept } } +bool +isUnaryOperator(OperatorKind kind) noexcept +{ + switch (kind) + { + case OperatorKind::Plus: + case OperatorKind::Minus: + case OperatorKind::Star: + case OperatorKind::Amp: + case OperatorKind::Tilde: + case OperatorKind::Exclaim: + case OperatorKind::PlusPlus: + case OperatorKind::MinusMinus: + case OperatorKind::New: + case OperatorKind::Delete: + case OperatorKind::ArrayNew: + case OperatorKind::ArrayDelete: + case OperatorKind::Coawait: + return true; + default: + return false; + } +} + +bool +isBinaryOperator(OperatorKind kind) noexcept +{ + switch (kind) + { + case OperatorKind::Plus: + case OperatorKind::Minus: + case OperatorKind::Star: + case OperatorKind::Slash: + case OperatorKind::Percent: + case OperatorKind::Caret: + case OperatorKind::Amp: + case OperatorKind::Pipe: + case OperatorKind::LessLess: + case OperatorKind::GreaterGreater: + case OperatorKind::Equal: + case OperatorKind::PlusEqual: + case OperatorKind::MinusEqual: + case OperatorKind::StarEqual: + case OperatorKind::SlashEqual: + case OperatorKind::PercentEqual: + case OperatorKind::CaretEqual: + case OperatorKind::AmpEqual: + case OperatorKind::PipeEqual: + case OperatorKind::LessLessEqual: + case OperatorKind::GreaterGreaterEqual: + case OperatorKind::EqualEqual: + case OperatorKind::ExclaimEqual: + case OperatorKind::Less: + case OperatorKind::LessEqual: + case OperatorKind::Greater: + case OperatorKind::GreaterEqual: + case OperatorKind::Spaceship: + case OperatorKind::AmpAmp: + case OperatorKind::PipePipe: + case OperatorKind::ArrowStar: + case OperatorKind::Arrow: + case OperatorKind::Call: + case OperatorKind::Subscript: + case OperatorKind::Comma: + return true; + default: + return false; + } +} + + } // clang } // mrdocs diff --git a/test-files/golden-tests/config/auto-brief/auto-brief.adoc b/test-files/golden-tests/config/auto-brief/auto-brief.adoc index 3511546b8..c0566d63a 100644 --- a/test-files/golden-tests/config/auto-brief/auto-brief.adoc +++ b/test-files/golden-tests/config/auto-brief/auto-brief.adoc @@ -23,9 +23,9 @@ | <> | Custom brief | <> -| This will not be copied. +| | <> -| This is more documentation. +| | <> | Custom brief | <> @@ -167,8 +167,6 @@ copyDetailsFromDocNoBrief(); [#copyDetailsFromExplicitBrief] == copyDetailsFromExplicitBrief -This will not be copied. - === Synopsis Declared in `<auto‐brief.cpp>` @@ -179,11 +177,13 @@ void copyDetailsFromExplicitBrief(); ---- +=== Description + +This description will never be copied as brief because it is an explicit brief. + [#copyDetailsFromFirstSentenceAsBrief] == copyDetailsFromFirstSentenceAsBrief -This is more documentation. - === Synopsis Declared in `<auto‐brief.cpp>` @@ -194,6 +194,10 @@ void copyDetailsFromFirstSentenceAsBrief(); ---- +=== Description + +This is more documentation. + [#copyDetailsFromNoDoc] == copyDetailsFromNoDoc @@ -226,7 +230,7 @@ copyDocFromCopyBrief(); === Description -This will not be copied. +This description will never be copied as brief because it is an explicit brief. [#copyDocFromExplicitBrief] == copyDocFromExplicitBrief @@ -245,7 +249,7 @@ copyDocFromExplicitBrief(); === Description -This will not be copied. +This description will never be copied as brief because it is an explicit brief. [#copyDocFromFirstSentenceAsBrief] == copyDocFromFirstSentenceAsBrief @@ -298,7 +302,7 @@ explicitBriefFunction(); === Description -This will not be copied. +This description will never be copied as brief because it is an explicit brief. [#explicitBriefFunction2] == explicitBriefFunction2 @@ -317,7 +321,7 @@ explicitBriefFunction2(); === Description -This will not be copied. +This will not be copied as brief. [#failCircularReferenceCopyFunction] == failCircularReferenceCopyFunction diff --git a/test-files/golden-tests/config/auto-brief/auto-brief.cpp b/test-files/golden-tests/config/auto-brief/auto-brief.cpp index db7fd28bb..e7f1d068f 100644 --- a/test-files/golden-tests/config/auto-brief/auto-brief.cpp +++ b/test-files/golden-tests/config/auto-brief/auto-brief.cpp @@ -11,12 +11,13 @@ void docNoBriefFunction(); /** * @brief This is the explicit brief. * - * This will not be copied. + * This description will never be copied as + * brief because it is an explicit brief. */ void explicitBriefFunction(); /** - * This will not be copied. + * This will not be copied as brief. * * @brief This is the explicit brief. */ diff --git a/test-files/golden-tests/config/auto-brief/auto-brief.html b/test-files/golden-tests/config/auto-brief/auto-brief.html index e42b5d57c..fdda96e68 100644 --- a/test-files/golden-tests/config/auto-brief/auto-brief.html +++ b/test-files/golden-tests/config/auto-brief/auto-brief.html @@ -25,8 +25,8 @@

Functions

copyBriefFromFirstValid This function has documentation but no brief. copyDetailsFromCopyBrief Details will be copied copyDetailsFromDocNoBrief Custom brief -copyDetailsFromExplicitBrief This will not be copied. -copyDetailsFromFirstSentenceAsBrief This is more documentation. +copyDetailsFromExplicitBrief +copyDetailsFromFirstSentenceAsBrief copyDetailsFromNoDoc Custom brief copyDocFromCopyBrief This is the explicit brief. copyDocFromExplicitBrief This is the explicit brief. @@ -177,10 +177,6 @@

Synopsis

copyDetailsFromExplicitBrief

-
-This will not be copied. - -

Synopsis

@@ -193,14 +189,14 @@

Synopsis

+
+

Description

+

This description will never be copied as brief because it is an explicit brief.

+

copyDetailsFromFirstSentenceAsBrief

-
-This is more documentation. - -

Synopsis

@@ -213,6 +209,10 @@

Synopsis

+
+

Description

+

This is more documentation.

+
@@ -255,7 +255,7 @@

Synopsis

Description

-

This will not be copied.

+

This description will never be copied as brief because it is an explicit brief.

@@ -279,7 +279,7 @@

Synopsis

Description

-

This will not be copied.

+

This description will never be copied as brief because it is an explicit brief.

@@ -347,7 +347,7 @@

Synopsis

Description

-

This will not be copied.

+

This description will never be copied as brief because it is an explicit brief.

@@ -371,7 +371,7 @@

Synopsis

Description

-

This will not be copied.

+

This will not be copied as brief.

diff --git a/test-files/golden-tests/config/auto-brief/auto-brief.xml b/test-files/golden-tests/config/auto-brief/auto-brief.xml index 1eabb762c..a53007dee 100644 --- a/test-files/golden-tests/config/auto-brief/auto-brief.xml +++ b/test-files/golden-tests/config/auto-brief/auto-brief.xml @@ -3,7 +3,7 @@ xsi:noNamespaceSchemaLocation="https://github.com/cppalliance/mrdocs/raw/develop/mrdocs.rnc"> - + This is the explicit brief. @@ -11,7 +11,7 @@ - + This is the explicit brief. @@ -19,7 +19,7 @@ - + This is the brief. @@ -27,7 +27,7 @@ - + This function has documentation but no brief. @@ -35,7 +35,7 @@ - + Details will be copied @@ -43,7 +43,7 @@ - + Custom brief @@ -51,23 +51,23 @@ - + - - This will not be copied. - + + This description will never be copied as brief because it is an explicit brief. + - + - + This is more documentation. - + - + Custom brief @@ -75,29 +75,29 @@ - + This is the explicit brief. - This will not be copied. + This description will never be copied as brief because it is an explicit brief. - + This is the explicit brief. - This will not be copied. + This description will never be copied as brief because it is an explicit brief. - + This is the brief. @@ -116,44 +116,50 @@ - + This is the explicit brief. - This will not be copied. + This description will never be copied as brief because it is an explicit brief. - + This is the explicit brief. - This will not be copied. + This will not be copied as brief. - + + + - + + + - + + + - + This function has documentation but no brief. @@ -161,22 +167,26 @@ - + + + - + + + - + - + This function has documentation but no brief. @@ -184,22 +194,28 @@ - + + + - + + + - + + + - + This is the brief. @@ -213,7 +229,7 @@ - + Final recursive brief @@ -221,7 +237,7 @@ - + Final recursive brief @@ -229,7 +245,7 @@ - + Final recursive brief diff --git a/test-files/golden-tests/config/auto-brief/no-auto-brief.adoc b/test-files/golden-tests/config/auto-brief/no-auto-brief.adoc index 13ba6af75..7d625af33 100644 --- a/test-files/golden-tests/config/auto-brief/no-auto-brief.adoc +++ b/test-files/golden-tests/config/auto-brief/no-auto-brief.adoc @@ -17,7 +17,7 @@ | <> | | <> -| +| This is the explicit brief. | <> | Details will be copied | <> @@ -120,6 +120,8 @@ copyBriefFromFirstSentenceAsBrief(); [#copyBriefFromFirstValid] == copyBriefFromFirstValid +This is the explicit brief. + === Synopsis Declared in `<no‐auto‐brief.cpp>` diff --git a/test-files/golden-tests/config/auto-brief/no-auto-brief.html b/test-files/golden-tests/config/auto-brief/no-auto-brief.html index 77178e414..a3171812c 100644 --- a/test-files/golden-tests/config/auto-brief/no-auto-brief.html +++ b/test-files/golden-tests/config/auto-brief/no-auto-brief.html @@ -22,7 +22,7 @@

Functions

copyBriefFromCopyBrief This is the explicit brief. copyBriefFromExplicitBrief This is the explicit brief. copyBriefFromFirstSentenceAsBrief -copyBriefFromFirstValid +copyBriefFromFirstValid This is the explicit brief. copyDetailsFromCopyBrief Details will be copied copyDetailsFromDocNoBrief Custom brief copyDetailsFromExplicitBrief @@ -113,6 +113,10 @@

Synopsis

copyBriefFromFirstValid

+
+This is the explicit brief. + +

Synopsis

diff --git a/test-files/golden-tests/config/auto-brief/no-auto-brief.xml b/test-files/golden-tests/config/auto-brief/no-auto-brief.xml index 76486b0fb..14eaf504a 100644 --- a/test-files/golden-tests/config/auto-brief/no-auto-brief.xml +++ b/test-files/golden-tests/config/auto-brief/no-auto-brief.xml @@ -21,11 +21,16 @@ + + + + This is the explicit brief. + @@ -96,6 +101,8 @@ + + This is the brief. @@ -137,31 +144,43 @@ + + + + + + + + + + + + @@ -172,6 +191,8 @@ + + This function has documentation but no brief. @@ -180,16 +201,22 @@ + + + + + + diff --git a/test-files/golden-tests/config/auto-function-metadata/brief-from-function-class.adoc b/test-files/golden-tests/config/auto-function-metadata/brief-from-function-class.adoc new file mode 100644 index 000000000..ced181efd --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/brief-from-function-class.adoc @@ -0,0 +1,323 @@ += Reference +:mrdocs: + +[#index] +== Global namespace + +=== Types + +[cols=2] +|=== +| Name +| Description +| <> +| A helper tag +| <> +| Test class +|=== + +[#A] +== A + +A helper tag + +=== Synopsis + +Declared in `<brief‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +struct A; +---- + +[#X] +== X + +Test class + +=== Synopsis + +Declared in `<brief‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +struct X; +---- + +=== Member Functions + +[cols=2] +|=== +| Name +| Description +| <> [.small]#[constructor]# +| Constructors +| <> [.small]#[destructor]# +| Destructor +| <> +| Conversion to `A` +| <> +| Conversion to `int` +|=== + +[#X-2constructor-08] +== <>::X + +Constructors + +=== Synopses + +Declared in `<brief‐from‐function‐class.cpp>` + +Default constructor + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +constexpr +<>() = default; +---- + +[.small]#<># + +Copy constructor + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +constexpr +<>(<> const& other) = default; +---- + +[.small]#<># + +Move constructor + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +constexpr +<>(<>&& other) = default; +---- + +[.small]#<># + +Construct from `int` + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>(int value); +---- + +[.small]#<># + +Construct from `A` + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>(<> const& value); +---- + +[.small]#<># + +Construct from `A` + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>(<>&& value); +---- + +[.small]#<># + +[#X-2constructor-0e8] +== <>::X + +Default constructor + +=== Synopsis + +Declared in `<brief‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +constexpr +X() = default; +---- + +[#X-2constructor-0e0] +== <>::X + +Copy constructor + +=== Synopsis + +Declared in `<brief‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +constexpr +X(<> const& other) = default; +---- + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *other* +| The object to copy construct from +|=== + +[#X-2constructor-06] +== <>::X + +Move constructor + +=== Synopsis + +Declared in `<brief‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +constexpr +X(<>&& other) = default; +---- + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *other* +| The object to move construct from +|=== + +[#X-2constructor-07] +== <>::X + +Construct from `int` + +=== Synopsis + +Declared in `<brief‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +X(int value); +---- + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *value* +| The value to construct from +|=== + +[#X-2constructor-0b] +== <>::X + +Construct from `A` + +=== Synopsis + +Declared in `<brief‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +X(<> const& value); +---- + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *value* +| The object to copy construct from +|=== + +[#X-2constructor-00] +== <>::X + +Construct from `A` + +=== Synopsis + +Declared in `<brief‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +X(<>&& value); +---- + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *value* +| The object to move construct from +|=== + +[#X-2destructor] +== <>::~X + +Destructor + +=== Synopsis + +Declared in `<brief‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +~X(); +---- + +[#X-2conversion-00] +== <>::operator <> + +Conversion to `A` + +=== Synopsis + +Declared in `<brief‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +operator <>() const; +---- + +=== Return Value + +A helper tag + +[#X-2conversion-0b] +== <>::operator int + +Conversion to `int` + +=== Synopsis + +Declared in `<brief‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +operator int() const; +---- + +=== Return Value + +The object converted to `int` + + +[.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/test-files/golden-tests/config/auto-function-metadata/brief-from-function-class.cpp b/test-files/golden-tests/config/auto-function-metadata/brief-from-function-class.cpp new file mode 100644 index 000000000..efa711cba --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/brief-from-function-class.cpp @@ -0,0 +1,17 @@ +/// A helper tag +struct A +{}; + +/// Test class +struct X +{ + X() = default; + X(X const&) = default; + X(X&&) = default; + X(A const&); + X(A&&); + X(int); + ~X(); + operator int() const; + operator A() const; +}; \ No newline at end of file diff --git a/test-files/golden-tests/config/auto-function-metadata/brief-from-function-class.html b/test-files/golden-tests/config/auto-function-metadata/brief-from-function-class.html new file mode 100644 index 000000000..893d99bd2 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/brief-from-function-class.html @@ -0,0 +1,420 @@ + + +Reference + + +
+

Reference

+
+
+

Global namespace

+
+

Types

+ + + + + + + + + + + + +
NameDescription
A A helper tag
X Test class
+ +
+
+
+

A

+
+A helper tag + +
+
+
+

Synopsis

+
+Declared in <brief-from-function-class.cpp>
+
+
+struct A;
+
+
+
+ + +
+
+
+

X

+
+Test class + +
+
+
+

Synopsis

+
+Declared in <brief-from-function-class.cpp>
+
+
+struct X;
+
+
+
+

Member Functions

+ + + + + + + + + + + + + + +
NameDescription
X [constructor]Constructors
~X [destructor]Destructor
operator A Conversion to A
operator int Conversion to int
+ + + +
+
+
+

X::X

+
+Constructors + +
+
+
+

Synopses

+
+Declared in <brief-from-function-class.cpp>
+Default constructor +
+
+constexpr
+X() = default;
+
+
» more... + +Copy constructor +
+
+constexpr
+X(X const& other) = default;
+
+
» more... + +Move constructor +
+
+constexpr
+X(X&& other) = default;
+
+
» more... + +Construct from int +
+
+X(int value);
+
+
» more... + +Construct from A +
+
+X(A const& value);
+
+
» more... + +Construct from A +
+
+X(A&& value);
+
+
» more... + + +
+
+
+
+

X::X

+
+Default constructor + +
+
+
+

Synopsis

+
+Declared in <brief-from-function-class.cpp>
+
+
+constexpr
+X() = default;
+
+
+
+
+
+
+

X::X

+
+Copy constructor + +
+
+
+

Synopsis

+
+Declared in <brief-from-function-class.cpp>
+
+
+constexpr
+X(X const& other) = default;
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
otherThe object to copy construct from
+
+
+
+
+

X::X

+
+Move constructor + +
+
+
+

Synopsis

+
+Declared in <brief-from-function-class.cpp>
+
+
+constexpr
+X(X&& other) = default;
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
otherThe object to move construct from
+
+
+
+
+

X::X

+
+Construct from int + +
+
+
+

Synopsis

+
+Declared in <brief-from-function-class.cpp>
+
+
+X(int value);
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
valueThe value to construct from
+
+
+
+
+

X::X

+
+Construct from A + +
+
+
+

Synopsis

+
+Declared in <brief-from-function-class.cpp>
+
+
+X(A const& value);
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
valueThe object to copy construct from
+
+
+
+
+

X::X

+
+Construct from A + +
+
+
+

Synopsis

+
+Declared in <brief-from-function-class.cpp>
+
+
+X(A&& value);
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
valueThe object to move construct from
+
+
+
+
+

X::~X

+
+Destructor + +
+
+
+

Synopsis

+
+Declared in <brief-from-function-class.cpp>
+
+
+~X();
+
+
+
+
+
+
+

X::operator A

+
+Conversion to A + +
+
+
+

Synopsis

+
+Declared in <brief-from-function-class.cpp>
+
+
+operator A() const;
+
+
+
+
+

Return Value

+A helper tag +
+
+
+
+

X::operator int

+
+Conversion to int + +
+
+
+

Synopsis

+
+Declared in <brief-from-function-class.cpp>
+
+
+operator int() const;
+
+
+
+
+

Return Value

+The object converted to int +
+
+ +
+
+

Created with MrDocs

+
+ + \ No newline at end of file diff --git a/test-files/golden-tests/config/auto-function-metadata/brief-from-function-class.xml b/test-files/golden-tests/config/auto-function-metadata/brief-from-function-class.xml new file mode 100644 index 000000000..b5be0885a --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/brief-from-function-class.xml @@ -0,0 +1,161 @@ + + + + + + + + A helper tag + + + + + + + + Test class + + + + + + + + + + Default constructor + + + + + + + + + + + + + + + + Copy constructor + + + The object to copy construct from + + + + + + + + + + + + + + + + Move constructor + + + The object to move construct from + + + + + + + + + + + Construct from + int + + + The value to construct from + + + + + + + + + + + + + Construct from + A + + + The object to copy construct from + + + + + + + + + + + + + Construct from + A + + + The object to move construct from + + + + + + + + Destructor + + + + + + + + + + + + Conversion to + A + + + A helper tag + + + + + + + + + + + + Conversion to + int + + + The object converted to + int + + + + + + diff --git a/test-files/golden-tests/config/auto-function-metadata/brief-from-function-class.yml b/test-files/golden-tests/config/auto-function-metadata/brief-from-function-class.yml new file mode 100644 index 000000000..2bdf9b1c4 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/brief-from-function-class.yml @@ -0,0 +1 @@ +auto-function-metadata: true \ No newline at end of file diff --git a/test-files/golden-tests/config/auto-function-metadata/brief-from-operator.adoc b/test-files/golden-tests/config/auto-function-metadata/brief-from-operator.adoc new file mode 100644 index 000000000..b491049ee --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/brief-from-operator.adoc @@ -0,0 +1,277 @@ += Reference +:mrdocs: + +[#index] +== Global namespace + +=== Types + +[cols=2] +|=== +| Name +| Description +| <> +| A helper tag +| <> +| Test class +| <> +| A dumb ostream class +|=== + +=== Functions + +[cols=2] +|=== +| Name +| Description +| <> +| Stream insertion operator +|=== + +[#A] +== A + +A helper tag + +=== Synopsis + +Declared in `<brief‐from‐operator.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +struct A; +---- + +[#X] +== X + +Test class + +=== Synopsis + +Declared in `<brief‐from‐operator.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +struct X; +---- + +=== Member Functions + +[cols=2] +|=== +| Name +| Description +| <> +| Assignment operators +| <> +| Addition assignment operator +|=== + +[#X-operator_assign-0a] +== <>::operator= + +Assignment operators + +=== Synopses + +Declared in `<brief‐from‐operator.cpp>` + +Copy assignment operator + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +<>(<> const& other); +---- + +[.small]#<># + +Move assignment operator + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +<>(<>&& other); +---- + +[.small]#<># + +Assignment operator + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +<>(<> const& value); +---- + +[.small]#<># + +[#X-operator_assign-06] +== <>::operator= + +Copy assignment operator + +=== Synopsis + +Declared in `<brief‐from‐operator.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +operator=(<> const& other); +---- + +=== Return Value + +Reference to the current object + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *other* +| The object to copy assign from +|=== + +[#X-operator_assign-0e] +== <>::operator= + +Move assignment operator + +=== Synopsis + +Declared in `<brief‐from‐operator.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +operator=(<>&& other); +---- + +=== Return Value + +Reference to the current object + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *other* +| The object to move assign from +|=== + +[#X-operator_assign-0d] +== <>::operator= + +Assignment operator + +=== Synopsis + +Declared in `<brief‐from‐operator.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +operator=(<> const& value); +---- + +=== Return Value + +Reference to the current object + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *value* +| The object to copy assign from +|=== + +[#X-operator_plus_eq] +== <>::operator+= + +Addition assignment operator + +=== Synopsis + +Declared in `<brief‐from‐operator.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +operator+=(<> const& rhs); +---- + +=== Return Value + +Reference to the current object + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *rhs* +| The right operand +|=== + +[#ostream] +== ostream + +A dumb ostream class + +=== Synopsis + +Declared in `<brief‐from‐operator.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +struct ostream; +---- + +[#operator_lshift] +== operator<< + +Stream insertion operator + +=== Synopsis + +Declared in `<brief‐from‐operator.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +operator<<( + <>& os, + <> const& x); +---- + +=== Return Value + +Reference to the current output stream + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *os* +| An output stream +| *x* +| The object to output +|=== + + +[.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/test-files/golden-tests/config/auto-function-metadata/brief-from-operator.cpp b/test-files/golden-tests/config/auto-function-metadata/brief-from-operator.cpp new file mode 100644 index 000000000..da1ccb30b --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/brief-from-operator.cpp @@ -0,0 +1,28 @@ +/// A helper tag +struct A +{}; + +/// A dumb ostream class +struct ostream {}; + +/// Test class +struct X +{ + X& + operator=(X const&); + + X& + operator=(X&&); + + X& + operator=(A const&); + + X& + operator+=(X const&); +}; + +ostream& +operator<<(ostream& os, X const& x) +{ + return os; +} diff --git a/test-files/golden-tests/config/auto-function-metadata/brief-from-operator.html b/test-files/golden-tests/config/auto-function-metadata/brief-from-operator.html new file mode 100644 index 000000000..e1c5f5c97 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/brief-from-operator.html @@ -0,0 +1,377 @@ + + +Reference + + +
+

Reference

+
+
+

Global namespace

+
+

Types

+ + + + + + + + + + + + + +
NameDescription
A A helper tag
X Test class
ostream A dumb ostream class
+ +

Functions

+ + + + + + + + + + + +
NameDescription
operator<< Stream insertion operator
+ +
+
+
+

A

+
+A helper tag + +
+
+
+

Synopsis

+
+Declared in <brief-from-operator.cpp>
+
+
+struct A;
+
+
+
+ + +
+
+
+

X

+
+Test class + +
+
+
+

Synopsis

+
+Declared in <brief-from-operator.cpp>
+
+
+struct X;
+
+
+
+

Member Functions

+ + + + + + + + + + + + +
NameDescription
operator= Assignment operators
operator+= Addition assignment operator
+ + + +
+
+
+

X::operator=

+
+Assignment operators + +
+
+
+

Synopses

+
+Declared in <brief-from-operator.cpp>
+Copy assignment operator +
+
+X&
+operator=(X const& other);
+
+
» more... + +Move assignment operator +
+
+X&
+operator=(X&& other);
+
+
» more... + +Assignment operator +
+
+X&
+operator=(A const& value);
+
+
» more... + + +
+
+
+
+

X::operator=

+
+Copy assignment operator + +
+
+
+

Synopsis

+
+Declared in <brief-from-operator.cpp>
+
+
+X&
+operator=(X const& other);
+
+
+
+
+

Return Value

+Reference to the current object +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
otherThe object to copy assign from
+
+
+
+
+

X::operator=

+
+Move assignment operator + +
+
+
+

Synopsis

+
+Declared in <brief-from-operator.cpp>
+
+
+X&
+operator=(X&& other);
+
+
+
+
+

Return Value

+Reference to the current object +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
otherThe object to move assign from
+
+
+
+
+

X::operator=

+
+Assignment operator + +
+
+
+

Synopsis

+
+Declared in <brief-from-operator.cpp>
+
+
+X&
+operator=(A const& value);
+
+
+
+
+

Return Value

+Reference to the current object +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
valueThe object to copy assign from
+
+
+
+
+

X::operator+=

+
+Addition assignment operator + +
+
+
+

Synopsis

+
+Declared in <brief-from-operator.cpp>
+
+
+X&
+operator+=(X const& rhs);
+
+
+
+
+

Return Value

+Reference to the current object +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
rhsThe right operand
+
+
+
+
+

ostream

+
+A dumb ostream class + +
+
+
+

Synopsis

+
+Declared in <brief-from-operator.cpp>
+
+
+struct ostream;
+
+
+
+ + +
+
+
+

operator<<

+
+Stream insertion operator + +
+
+
+

Synopsis

+
+Declared in <brief-from-operator.cpp>
+
+
+ostream&
+operator<<(
+    ostream& os,
+    X const& x);
+
+
+
+
+

Return Value

+Reference to the current output stream +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
osAn output stream
xThe object to output
+
+
+ +
+
+

Created with MrDocs

+
+ + \ No newline at end of file diff --git a/test-files/golden-tests/config/auto-function-metadata/brief-from-operator.xml b/test-files/golden-tests/config/auto-function-metadata/brief-from-operator.xml new file mode 100644 index 000000000..7acdca1ae --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/brief-from-operator.xml @@ -0,0 +1,163 @@ + + + + + + + + A helper tag + + + + + + + + Test class + + + + + + + + + + + + + + + + + + Copy assignment operator + + + Reference to the current object + + + The object to copy assign from + + + + + + + + + + + + + + + + + + + Move assignment operator + + + Reference to the current object + + + The object to move assign from + + + + + + + + + + + + + + + + + + + Assignment operator + + + Reference to the current object + + + The object to copy assign from + + + + + + + + + + + + + + + + + + + Addition assignment operator + + + Reference to the current object + + + The right operand + + + + + + + + + A dumb ostream class + + + + + + + + + + + + + + + + + + + + + + + + Stream insertion operator + + + Reference to the current output stream + + + An output stream + + + The object to output + + + + + diff --git a/test-files/golden-tests/config/auto-function-metadata/brief-from-operator.yml b/test-files/golden-tests/config/auto-function-metadata/brief-from-operator.yml new file mode 100644 index 000000000..2bdf9b1c4 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/brief-from-operator.yml @@ -0,0 +1 @@ +auto-function-metadata: true \ No newline at end of file diff --git a/test-files/golden-tests/config/auto-function-metadata/param-from-function-class.adoc b/test-files/golden-tests/config/auto-function-metadata/param-from-function-class.adoc new file mode 100644 index 000000000..71d939e1e --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/param-from-function-class.adoc @@ -0,0 +1,448 @@ += Reference +:mrdocs: + +[#index] +== Global namespace + +=== Types + +[cols=2] +|=== +| Name +| Description +| <> +| A helper tag +| <> +| Test class +|=== + +[#A] +== A + +A helper tag + +=== Synopsis + +Declared in `<param‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +struct A; +---- + +[#X] +== X + +Test class + +=== Synopsis + +Declared in `<param‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +struct X; +---- + +=== Member Functions + +[cols=2] +|=== +| Name +| Description +| <> [.small]#[constructor]# +| Constructors +| <> +| Assignment operators +|=== + +[#X-2constructor-08] +== <>::X + +Constructors + +=== Synopses + +Declared in `<param‐from‐function‐class.cpp>` + +Copy constructor + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>(<> const& other); +---- + +[.small]#<># + +Move constructor + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>(<>&& other); +---- + +[.small]#<># + +Construct from `int` + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>(int value); +---- + +[.small]#<># + +Construct from `A` + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>(<> const& value); +---- + +[.small]#<># + +Construct from `A` + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>(<>&& value); +---- + +[.small]#<># + +[#X-2constructor-0e] +== <>::X + +Copy constructor + +=== Synopsis + +Declared in `<param‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +X(<> const& other); +---- + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *other* +| The object to copy construct from +|=== + +[#X-2constructor-06] +== <>::X + +Move constructor + +=== Synopsis + +Declared in `<param‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +X(<>&& other); +---- + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *other* +| The object to move construct from +|=== + +[#X-2constructor-07] +== <>::X + +Construct from `int` + +=== Synopsis + +Declared in `<param‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +X(int value); +---- + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *value* +| The value to construct from +|=== + +[#X-2constructor-0b] +== <>::X + +Construct from `A` + +=== Synopsis + +Declared in `<param‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +X(<> const& value); +---- + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *value* +| The object to copy construct from +|=== + +[#X-2constructor-00] +== <>::X + +Construct from `A` + +=== Synopsis + +Declared in `<param‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +X(<>&& value); +---- + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *value* +| The object to move construct from +|=== + +[#X-operator_assign-0a] +== <>::operator= + +Assignment operators + +=== Synopses + +Declared in `<param‐from‐function‐class.cpp>` + +Copy assignment operator + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +<>(<> const& other); +---- + +[.small]#<># + +Move assignment operator + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +<>(<>&& other); +---- + +[.small]#<># + +Assignment operator + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +<>(int value); +---- + +[.small]#<># + +Assignment operator + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +<>(<> const& value); +---- + +[.small]#<># + +Assignment operator + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +<>(<>&& value); +---- + +[.small]#<># + +[#X-operator_assign-06] +== <>::operator= + +Copy assignment operator + +=== Synopsis + +Declared in `<param‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +operator=(<> const& other); +---- + +=== Return Value + +Reference to the current object + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *other* +| The object to copy assign from +|=== + +[#X-operator_assign-0e] +== <>::operator= + +Move assignment operator + +=== Synopsis + +Declared in `<param‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +operator=(<>&& other); +---- + +=== Return Value + +Reference to the current object + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *other* +| The object to move assign from +|=== + +[#X-operator_assign-07f] +== <>::operator= + +Assignment operator + +=== Synopsis + +Declared in `<param‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +operator=(int value); +---- + +=== Return Value + +Reference to the current object + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *value* +| The value to assign from +|=== + +[#X-operator_assign-0d] +== <>::operator= + +Assignment operator + +=== Synopsis + +Declared in `<param‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +operator=(<> const& value); +---- + +=== Return Value + +Reference to the current object + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *value* +| The object to copy assign from +|=== + +[#X-operator_assign-07e] +== <>::operator= + +Assignment operator + +=== Synopsis + +Declared in `<param‐from‐function‐class.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +operator=(<>&& value); +---- + +=== Return Value + +Reference to the current object + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *value* +| The object to move assign from +|=== + + +[.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/test-files/golden-tests/config/auto-function-metadata/param-from-function-class.cpp b/test-files/golden-tests/config/auto-function-metadata/param-from-function-class.cpp new file mode 100644 index 000000000..326ecf5e8 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/param-from-function-class.cpp @@ -0,0 +1,32 @@ +/// A helper tag +struct A +{}; + +/// Test class +struct X +{ + X(X const& other); + + X(X&& other); + + X(A const& value); + + X(A&& value); + + X(int value); + + X& + operator=(X const& other); + + X& + operator=(X&& other); + + X& + operator=(A const& value); + + X& + operator=(A&& value); + + X& + operator=(int value); +}; diff --git a/test-files/golden-tests/config/auto-function-metadata/param-from-function-class.html b/test-files/golden-tests/config/auto-function-metadata/param-from-function-class.html new file mode 100644 index 000000000..1d90ec5f3 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/param-from-function-class.html @@ -0,0 +1,581 @@ + + +Reference + + +
+

Reference

+
+
+

Global namespace

+
+

Types

+ + + + + + + + + + + + +
NameDescription
A A helper tag
X Test class
+ +
+
+
+

A

+
+A helper tag + +
+
+
+

Synopsis

+
+Declared in <param-from-function-class.cpp>
+
+
+struct A;
+
+
+
+ + +
+
+
+

X

+
+Test class + +
+
+
+

Synopsis

+
+Declared in <param-from-function-class.cpp>
+
+
+struct X;
+
+
+
+

Member Functions

+ + + + + + + + + + + + +
NameDescription
X [constructor]Constructors
operator= Assignment operators
+ + + +
+
+
+

X::X

+
+Constructors + +
+
+
+

Synopses

+
+Declared in <param-from-function-class.cpp>
+Copy constructor +
+
+X(X const& other);
+
+
» more... + +Move constructor +
+
+X(X&& other);
+
+
» more... + +Construct from int +
+
+X(int value);
+
+
» more... + +Construct from A +
+
+X(A const& value);
+
+
» more... + +Construct from A +
+
+X(A&& value);
+
+
» more... + + +
+
+
+
+

X::X

+
+Copy constructor + +
+
+
+

Synopsis

+
+Declared in <param-from-function-class.cpp>
+
+
+X(X const& other);
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
otherThe object to copy construct from
+
+
+
+
+

X::X

+
+Move constructor + +
+
+
+

Synopsis

+
+Declared in <param-from-function-class.cpp>
+
+
+X(X&& other);
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
otherThe object to move construct from
+
+
+
+
+

X::X

+
+Construct from int + +
+
+
+

Synopsis

+
+Declared in <param-from-function-class.cpp>
+
+
+X(int value);
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
valueThe value to construct from
+
+
+
+
+

X::X

+
+Construct from A + +
+
+
+

Synopsis

+
+Declared in <param-from-function-class.cpp>
+
+
+X(A const& value);
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
valueThe object to copy construct from
+
+
+
+
+

X::X

+
+Construct from A + +
+
+
+

Synopsis

+
+Declared in <param-from-function-class.cpp>
+
+
+X(A&& value);
+
+
+
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
valueThe object to move construct from
+
+
+
+
+

X::operator=

+
+Assignment operators + +
+
+
+

Synopses

+
+Declared in <param-from-function-class.cpp>
+Copy assignment operator +
+
+X&
+operator=(X const& other);
+
+
» more... + +Move assignment operator +
+
+X&
+operator=(X&& other);
+
+
» more... + +Assignment operator +
+
+X&
+operator=(int value);
+
+
» more... + +Assignment operator +
+
+X&
+operator=(A const& value);
+
+
» more... + +Assignment operator +
+
+X&
+operator=(A&& value);
+
+
» more... + + +
+
+
+
+

X::operator=

+
+Copy assignment operator + +
+
+
+

Synopsis

+
+Declared in <param-from-function-class.cpp>
+
+
+X&
+operator=(X const& other);
+
+
+
+
+

Return Value

+Reference to the current object +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
otherThe object to copy assign from
+
+
+
+
+

X::operator=

+
+Move assignment operator + +
+
+
+

Synopsis

+
+Declared in <param-from-function-class.cpp>
+
+
+X&
+operator=(X&& other);
+
+
+
+
+

Return Value

+Reference to the current object +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
otherThe object to move assign from
+
+
+
+
+

X::operator=

+
+Assignment operator + +
+
+
+

Synopsis

+
+Declared in <param-from-function-class.cpp>
+
+
+X&
+operator=(int value);
+
+
+
+
+

Return Value

+Reference to the current object +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
valueThe value to assign from
+
+
+
+
+

X::operator=

+
+Assignment operator + +
+
+
+

Synopsis

+
+Declared in <param-from-function-class.cpp>
+
+
+X&
+operator=(A const& value);
+
+
+
+
+

Return Value

+Reference to the current object +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
valueThe object to copy assign from
+
+
+
+
+

X::operator=

+
+Assignment operator + +
+
+
+

Synopsis

+
+Declared in <param-from-function-class.cpp>
+
+
+X&
+operator=(A&& value);
+
+
+
+
+

Return Value

+Reference to the current object +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
valueThe object to move assign from
+
+
+ +
+
+

Created with MrDocs

+
+ + \ No newline at end of file diff --git a/test-files/golden-tests/config/auto-function-metadata/param-from-function-class.xml b/test-files/golden-tests/config/auto-function-metadata/param-from-function-class.xml new file mode 100644 index 000000000..09bd6cf95 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/param-from-function-class.xml @@ -0,0 +1,226 @@ + + + + + + + + A helper tag + + + + + + + + Test class + + + + + + + + + + + + Copy constructor + + + The object to copy construct from + + + + + + + + + + + + + Move constructor + + + The object to move construct from + + + + + + + + + + + Construct from + int + + + The value to construct from + + + + + + + + + + + + + Construct from + A + + + The object to copy construct from + + + + + + + + + + + + + Construct from + A + + + The object to move construct from + + + + + + + + + + + + + + + + + + + Copy assignment operator + + + Reference to the current object + + + The object to copy assign from + + + + + + + + + + + + + + + + + + + Move assignment operator + + + Reference to the current object + + + The object to move assign from + + + + + + + + + + + + + + + + + Assignment operator + + + Reference to the current object + + + The value to assign from + + + + + + + + + + + + + + + + + + + Assignment operator + + + Reference to the current object + + + The object to copy assign from + + + + + + + + + + + + + + + + + + + Assignment operator + + + Reference to the current object + + + The object to move assign from + + + + + + diff --git a/test-files/golden-tests/config/auto-function-metadata/param-from-function-class.yml b/test-files/golden-tests/config/auto-function-metadata/param-from-function-class.yml new file mode 100644 index 000000000..2bdf9b1c4 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/param-from-function-class.yml @@ -0,0 +1 @@ +auto-function-metadata: true \ No newline at end of file diff --git a/test-files/golden-tests/config/auto-function-metadata/param-from-operator.adoc b/test-files/golden-tests/config/auto-function-metadata/param-from-operator.adoc new file mode 100644 index 000000000..3be0d716d --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/param-from-operator.adoc @@ -0,0 +1,212 @@ += Reference +:mrdocs: + +[#index] +== Global namespace + +=== Types + +[cols=2] +|=== +| Name +| Description +| <> +| A helper tag +| <> +| Test class +| <> +| A dumb ostream class +|=== + +=== Functions + +[cols=2] +|=== +| Name +| Description +| <> +| Subtraction operator +| <> +| Stream insertion operator +| <> +| Negation operator +|=== + +[#A] +== A + +A helper tag + +=== Synopsis + +Declared in `<param‐from‐operator.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +struct A; +---- + +[#X] +== X + +Test class + +=== Synopsis + +Declared in `<param‐from‐operator.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +struct X; +---- + +=== Member Functions + +[cols=2] +|=== +| Name +| Description +| <> +| Addition operator +|=== + +[#X-operator_plus] +== <>::operator+ + +Addition operator + +=== Synopsis + +Declared in `<param‐from‐operator.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<> +operator+(<> const& x) const; +---- + +=== Return Value + +Another instance of the object + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *x* +| The right operand +|=== + +[#ostream] +== ostream + +A dumb ostream class + +=== Synopsis + +Declared in `<param‐from‐operator.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +struct ostream; +---- + +[#operator_minus] +== operator‐ + +Subtraction operator + +=== Synopsis + +Declared in `<param‐from‐operator.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<> +operator‐( + <> const& x, + <> const& y); +---- + +=== Return Value + +Test class + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *x* +| The left operand +| *y* +| The right operand +|=== + +[#operator_lshift] +== operator<< + +Stream insertion operator + +=== Synopsis + +Declared in `<param‐from‐operator.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +operator<<( + <>& os, + <> const& x); +---- + +=== Return Value + +Reference to the current output stream + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *os* +| An output stream +| *x* +| The object to output +|=== + +[#operator_not] +== operator! + +Negation operator + +=== Synopsis + +Declared in `<param‐from‐operator.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<> +operator!(<> const& x); +---- + +=== Return Value + +Test class + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *x* +| The operand +|=== + + +[.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/test-files/golden-tests/config/auto-function-metadata/param-from-operator.cpp b/test-files/golden-tests/config/auto-function-metadata/param-from-operator.cpp new file mode 100644 index 000000000..edc902e1e --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/param-from-operator.cpp @@ -0,0 +1,25 @@ +/// A helper tag +struct A +{}; + +/// A dumb ostream class +struct ostream {}; + +/// Test class +struct X +{ + X + operator+(X const& x) const; +}; + +X +operator-(X const& x, X const& y); + +X +operator!(X const& x); + +ostream& +operator<<(ostream& os, X const& x) +{ + return os; +} diff --git a/test-files/golden-tests/config/auto-function-metadata/param-from-operator.html b/test-files/golden-tests/config/auto-function-metadata/param-from-operator.html new file mode 100644 index 000000000..9a0b95cae --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/param-from-operator.html @@ -0,0 +1,304 @@ + + +Reference + + +
+

Reference

+
+
+

Global namespace

+
+

Types

+ + + + + + + + + + + + + +
NameDescription
A A helper tag
X Test class
ostream A dumb ostream class
+ +

Functions

+ + + + + + + + + + + + + +
NameDescription
operator- Subtraction operator
operator<< Stream insertion operator
operator! Negation operator
+ +
+
+
+

A

+
+A helper tag + +
+
+
+

Synopsis

+
+Declared in <param-from-operator.cpp>
+
+
+struct A;
+
+
+
+ + +
+
+
+

X

+
+Test class + +
+
+
+

Synopsis

+
+Declared in <param-from-operator.cpp>
+
+
+struct X;
+
+
+
+

Member Functions

+ + + + + + + + + + + +
NameDescription
operator+ Addition operator
+ + + +
+
+
+

X::operator+

+
+Addition operator + +
+
+
+

Synopsis

+
+Declared in <param-from-operator.cpp>
+
+
+X
+operator+(X const& x) const;
+
+
+
+
+

Return Value

+Another instance of the object +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
xThe right operand
+
+
+
+
+

ostream

+
+A dumb ostream class + +
+
+
+

Synopsis

+
+Declared in <param-from-operator.cpp>
+
+
+struct ostream;
+
+
+
+ + +
+
+
+

operator-

+
+Subtraction operator + +
+
+
+

Synopsis

+
+Declared in <param-from-operator.cpp>
+
+
+X
+operator-(
+    X const& x,
+    X const& y);
+
+
+
+
+

Return Value

+Test class +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
xThe left operand
yThe right operand
+
+
+
+
+

operator<<

+
+Stream insertion operator + +
+
+
+

Synopsis

+
+Declared in <param-from-operator.cpp>
+
+
+ostream&
+operator<<(
+    ostream& os,
+    X const& x);
+
+
+
+
+

Return Value

+Reference to the current output stream +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
osAn output stream
xThe object to output
+
+
+
+
+

operator!

+
+Negation operator + +
+
+
+

Synopsis

+
+Declared in <param-from-operator.cpp>
+
+
+X
+operator!(X const& x);
+
+
+
+
+

Return Value

+Test class +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
xThe operand
+
+
+ +
+
+

Created with MrDocs

+
+ + \ No newline at end of file diff --git a/test-files/golden-tests/config/auto-function-metadata/param-from-operator.xml b/test-files/golden-tests/config/auto-function-metadata/param-from-operator.xml new file mode 100644 index 000000000..534f8bc38 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/param-from-operator.xml @@ -0,0 +1,141 @@ + + + + + + + + A helper tag + + + + + + + + Test class + + + + + + + + + + + + + + + + + Addition operator + + + Another instance of the object + + + The right operand + + + + + + + + + A dumb ostream class + + + + + + + + + + + + + + + + + + + + + + Subtraction operator + + + Test class + + + The left operand + + + The right operand + + + + + + + + + + + + + + + + + + + + + + + + Stream insertion operator + + + Reference to the current output stream + + + An output stream + + + The object to output + + + + + + + + + + + + + + + + + Negation operator + + + Test class + + + The operand + + + + + diff --git a/test-files/golden-tests/config/auto-function-metadata/param-from-operator.yml b/test-files/golden-tests/config/auto-function-metadata/param-from-operator.yml new file mode 100644 index 000000000..2bdf9b1c4 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/param-from-operator.yml @@ -0,0 +1 @@ +auto-function-metadata: true \ No newline at end of file diff --git a/test-files/golden-tests/config/auto-function-metadata/returns-from-brief.adoc b/test-files/golden-tests/config/auto-function-metadata/returns-from-brief.adoc new file mode 100644 index 000000000..30503abc0 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/returns-from-brief.adoc @@ -0,0 +1,103 @@ += Reference +:mrdocs: + +[#index] +== Global namespace + +=== Types + +[cols=2] +|=== +| Name +| Description +| <> +| Test class +|=== + +[#X] +== X + +Test class + +=== Synopsis + +Declared in `<returns‐from‐brief.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +struct X; +---- + +=== Member Functions + +[cols=2] +|=== +| Name +| Description +| <> +| Determines whether the range is empty. +| <> +| Returns the first element of the range. +| <> +| Get the range size. +|=== + +[#X-empty] +== <>::empty + +Determines whether the range is empty. + +=== Synopsis + +Declared in `<returns‐from‐brief.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +bool +empty(); +---- + +=== Return Value + +whether the range is empty. + +[#X-front] +== <>::front + +Returns the first element of the range. + +=== Synopsis + +Declared in `<returns‐from‐brief.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +int +front() const; +---- + +=== Return Value + +the first element of the range. + +[#X-size] +== <>::size + +Get the range size. + +=== Synopsis + +Declared in `<returns‐from‐brief.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +int +size() const; +---- + +=== Return Value + +the range size. + + +[.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/test-files/golden-tests/config/auto-function-metadata/returns-from-brief.cpp b/test-files/golden-tests/config/auto-function-metadata/returns-from-brief.cpp new file mode 100644 index 000000000..21e38134d --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/returns-from-brief.cpp @@ -0,0 +1,15 @@ +/// Test class +struct X +{ + /// Returns the first element of the range. + int + front() const; + + /// Determines whether the range is empty. + bool + empty(); + + /// Get the range size. + int + size() const; +}; diff --git a/test-files/golden-tests/config/auto-function-metadata/returns-from-brief.html b/test-files/golden-tests/config/auto-function-metadata/returns-from-brief.html new file mode 100644 index 000000000..e56cab62a --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/returns-from-brief.html @@ -0,0 +1,142 @@ + + +Reference + + +
+

Reference

+
+
+

Global namespace

+
+

Types

+ + + + + + + + + + + +
NameDescription
X Test class
+ +
+
+
+

X

+
+Test class + +
+
+
+

Synopsis

+
+Declared in <returns-from-brief.cpp>
+
+
+struct X;
+
+
+
+

Member Functions

+ + + + + + + + + + + + + +
NameDescription
empty Determines whether the range is empty.
front Returns the first element of the range.
size Get the range size.
+ + + +
+
+
+

X::empty

+
+Determines whether the range is empty. + +
+
+
+

Synopsis

+
+Declared in <returns-from-brief.cpp>
+
+
+bool
+empty();
+
+
+
+
+

Return Value

+whether the range is empty. +
+
+
+
+

X::front

+
+Returns the first element of the range. + +
+
+
+

Synopsis

+
+Declared in <returns-from-brief.cpp>
+
+
+int
+front() const;
+
+
+
+
+

Return Value

+the first element of the range. +
+
+
+
+

X::size

+
+Get the range size. + +
+
+
+

Synopsis

+
+Declared in <returns-from-brief.cpp>
+
+
+int
+size() const;
+
+
+
+
+

Return Value

+the range size. +
+
+ +
+
+

Created with MrDocs

+
+ + \ No newline at end of file diff --git a/test-files/golden-tests/config/auto-function-metadata/returns-from-brief.xml b/test-files/golden-tests/config/auto-function-metadata/returns-from-brief.xml new file mode 100644 index 000000000..bbd3682d2 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/returns-from-brief.xml @@ -0,0 +1,58 @@ + + + + + + + + Test class + + + + + + + + + + Determines whether the range is empty. + + + whether the range is empty. + + + + + + + + + + + + Returns the first element of the range. + + + the first element of the range. + + + + + + + + + + + + Get the range size. + + + the range size. + + + + + + diff --git a/test-files/golden-tests/config/auto-function-metadata/returns-from-brief.yml b/test-files/golden-tests/config/auto-function-metadata/returns-from-brief.yml new file mode 100644 index 000000000..2bdf9b1c4 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/returns-from-brief.yml @@ -0,0 +1 @@ +auto-function-metadata: true \ No newline at end of file diff --git a/test-files/golden-tests/config/auto-function-metadata/returns-from-return-brief.adoc b/test-files/golden-tests/config/auto-function-metadata/returns-from-return-brief.adoc new file mode 100644 index 000000000..093be7c51 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/returns-from-return-brief.adoc @@ -0,0 +1,71 @@ += Reference +:mrdocs: + +[#index] +== Global namespace + +=== Types + +[cols=2] +|=== +| Name +| Description +| <> +| The return type of the function +|=== + +=== Functions + +[cols=2] +|=== +| Name +| Description +| <> +| Test function +|=== + +[#R] +== R + +The return type of the function + +=== Synopsis + +Declared in `<returns‐from‐return‐brief.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +struct R; +---- + +=== Non-Member Functions + +[,cols=2] +|=== +| Name +| Description +| <> +| Test function +|=== + +[#getR] +== getR + +Test function + +=== Synopsis + +Declared in `<returns‐from‐return‐brief.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<> +getR(); +---- + +=== Return Value + +The return type of the function + + +[.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/test-files/golden-tests/config/auto-function-metadata/returns-from-return-brief.cpp b/test-files/golden-tests/config/auto-function-metadata/returns-from-return-brief.cpp new file mode 100644 index 000000000..dd535ea8d --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/returns-from-return-brief.cpp @@ -0,0 +1,6 @@ +/// The return type of the function +struct R; + +/// Test function +R +getR(); \ No newline at end of file diff --git a/test-files/golden-tests/config/auto-function-metadata/returns-from-return-brief.html b/test-files/golden-tests/config/auto-function-metadata/returns-from-return-brief.html new file mode 100644 index 000000000..53eac380a --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/returns-from-return-brief.html @@ -0,0 +1,106 @@ + + +Reference + + +
+

Reference

+
+
+

Global namespace

+
+

Types

+ + + + + + + + + + + +
NameDescription
R The return type of the function
+ +

Functions

+ + + + + + + + + + + +
NameDescription
getR Test function
+ +
+
+
+

R

+
+The return type of the function + +
+
+
+

Synopsis

+
+Declared in <returns-from-return-brief.cpp>
+
+
+struct R;
+
+
+
+ + +
+

Non-Member Functions

+ + + + + + + + + + +
NameDescription
getRTest function
+
+
+
+
+

getR

+
+Test function + +
+
+
+

Synopsis

+
+Declared in <returns-from-return-brief.cpp>
+
+
+R
+getR();
+
+
+
+
+

Return Value

+The return type of the function +
+
+ +
+
+

Created with MrDocs

+
+ + \ No newline at end of file diff --git a/test-files/golden-tests/config/auto-function-metadata/returns-from-return-brief.xml b/test-files/golden-tests/config/auto-function-metadata/returns-from-return-brief.xml new file mode 100644 index 000000000..53bf51ec3 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/returns-from-return-brief.xml @@ -0,0 +1,34 @@ + + + + + + + + The return type of the function + + + getR + + + + + + + + + + + Test function + + + The return type of the function + + + R + + + + + diff --git a/test-files/golden-tests/config/auto-function-metadata/returns-from-return-brief.yml b/test-files/golden-tests/config/auto-function-metadata/returns-from-return-brief.yml new file mode 100644 index 000000000..2bdf9b1c4 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/returns-from-return-brief.yml @@ -0,0 +1 @@ +auto-function-metadata: true \ No newline at end of file diff --git a/test-files/golden-tests/config/auto-function-metadata/returns-from-special.adoc b/test-files/golden-tests/config/auto-function-metadata/returns-from-special.adoc new file mode 100644 index 000000000..bcbe1f47a --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/returns-from-special.adoc @@ -0,0 +1,826 @@ += Reference +:mrdocs: + +[#index] +== Global namespace + +=== Types + +[cols=2] +|=== +| Name +| Description +| <> +| A helper class +| <> +| +| <> +| Test class +| <> +| A fake output stream +|=== + +=== Functions + +[cols=2] +|=== +| Name +| Description +| <> +| Stream insertion operator +| <> +| Negation operator +| <> +| Equality operator +| <> +| Inequality operator +| <> +| Less‐than operator +| <> +| Less‐than‐or‐equal operator +| <> +| Greater‐than operator +| <> +| Greater‐than‐or‐equal operator +| <> +| Three‐way comparison operator +|=== + +[#A] +== A + +A helper class + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +struct A; +---- + +[#Undoc] +== Undoc + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +struct Undoc; +---- + +[#X] +== X + +Test class + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +struct X; +---- + +=== Member Functions + +[cols=2] +|=== +| Name +| Description +| <> +| Assignment operators +| <> +| Addition operator +| <> +| Member access operator +| <> +| Conversion to `A` +| <> +| Conversion to `Undoc` +| <> +| Negation operator +| <> +| Equality operator +| <> +| Inequality operator +| <> +| Less‐than operator +| <> +| Less‐than‐or‐equal operator +| <> +| Greater‐than operator +| <> +| Greater‐than‐or‐equal operator +| <> +| Three‐way comparison operator +|=== + +[#X-operator_assign-0a] +== <>::operator= + +Assignment operators + +=== Synopses + +Declared in `<returns‐from‐special.cpp>` + +Assignment operator + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +<>(<> const& value); +---- + +[.small]#<># + +Assignment operator + + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>&& +<>(<>&& value); +---- + +[.small]#<># + +[#X-operator_assign-0d] +== <>::operator= + +Assignment operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +operator=(<> const& value); +---- + +=== Return Value + +Reference to the current object + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *value* +| The object to copy assign from +|=== + +[#X-operator_assign-07] +== <>::operator= + +Assignment operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>&& +operator=(<>&& value); +---- + +=== Return Value + +Rvalue reference to the current object + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *value* +| The object to move assign from +|=== + +[#X-operator_plus] +== <>::operator+ + +Addition operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<> +operator+(<> const& rhs) const; +---- + +=== Return Value + +Another instance of the object + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *rhs* +| The right operand +|=== + +[#X-operator_ptr] +== <>::operator‐> + +Member access operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>* +operator‐>(); +---- + +=== Return Value + +Pointer to the current object + +[#X-2conversion-00] +== <>::operator <> + +Conversion to `A` + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +operator <>() const; +---- + +=== Return Value + +A helper class + +[#X-2conversion-03] +== <>::operator <> + +Conversion to `Undoc` + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +operator <>() const; +---- + +=== Return Value + +The object converted to `Undoc` + +[#X-operator_not] +== <>::operator! + +Negation operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +bool +operator!() const; +---- + +=== Return Value + +`true` if the object is falsy, `false` otherwise + +[#X-operator_eq] +== <>::operator== + +Equality operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +bool +operator==(<> const& rhs) const; +---- + +=== Return Value + +`true` if the objects are equal, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *rhs* +| The right operand +|=== + +[#X-operator_not_eq] +== <>::operator!= + +Inequality operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +bool +operator!=(<> const& rhs) const; +---- + +=== Return Value + +`true` if the objects are not equal, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *rhs* +| The right operand +|=== + +[#X-operator_lt] +== <>::operator< + +Less‐than operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +bool +operator<(<> const& rhs) const; +---- + +=== Return Value + +`true` if the left object is less than the right object, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *rhs* +| The right operand +|=== + +[#X-operator_le] +== <>::operator<= + +Less‐than‐or‐equal operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +bool +operator<=(<> const& rhs) const; +---- + +=== Return Value + +`true` if the left object is less than or equal to the right object, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *rhs* +| The right operand +|=== + +[#X-operator_gt] +== <>::operator> + +Greater‐than operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +bool +operator>(<> const& rhs) const; +---- + +=== Return Value + +`true` if the left object is greater than the right object, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *rhs* +| The right operand +|=== + +[#X-operator_ge] +== <>::operator>= + +Greater‐than‐or‐equal operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +bool +operator>=(<> const& rhs) const; +---- + +=== Return Value + +`true` if the left object is greater than or equal to the right object, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *rhs* +| The right operand +|=== + +[#X-operator_3way] +== <>::operator<=> + +Three‐way comparison operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +auto +operator<=>(<> const& rhs) const; +---- + +=== Return Value + +The relative order of the objects + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *rhs* +| The right operand +|=== + +[#ostream] +== ostream + +A fake output stream + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +struct ostream; +---- + +[#operator_lshift] +== operator<< + +Stream insertion operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +<>& +operator<<( + <>& os, + <> const& value); +---- + +=== Return Value + +Reference to the current output stream + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *os* +| An output stream +| *value* +| The object to output +|=== + +[#operator_not] +== operator! + +Negation operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +bool +operator!(<> const& value); +---- + +=== Return Value + +`true` if the object is falsy, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *value* +| The operand +|=== + +[#operator_eq] +== operator== + +Equality operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +bool +operator==( + <> const& lhs, + <> const& rhs); +---- + +=== Return Value + +`true` if the objects are equal, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *lhs* +| The left operand +| *rhs* +| The right operand +|=== + +[#operator_not_eq] +== operator!= + +Inequality operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +bool +operator!=( + <> const& lhs, + <> const& rhs); +---- + +=== Return Value + +`true` if the objects are not equal, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *lhs* +| The left operand +| *rhs* +| The right operand +|=== + +[#operator_lt] +== operator< + +Less‐than operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +bool +operator<( + <> const& lhs, + <> const& rhs); +---- + +=== Return Value + +`true` if the left object is less than the right object, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *lhs* +| The left operand +| *rhs* +| The right operand +|=== + +[#operator_le] +== operator<= + +Less‐than‐or‐equal operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +bool +operator<=( + <> const& lhs, + <> const& rhs); +---- + +=== Return Value + +`true` if the left object is less than or equal to the right object, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *lhs* +| The left operand +| *rhs* +| The right operand +|=== + +[#operator_gt] +== operator> + +Greater‐than operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +bool +operator>( + <> const& lhs, + <> const& rhs); +---- + +=== Return Value + +`true` if the left object is greater than the right object, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *lhs* +| The left operand +| *rhs* +| The right operand +|=== + +[#operator_ge] +== operator>= + +Greater‐than‐or‐equal operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +bool +operator>=( + <> const& lhs, + <> const& rhs); +---- + +=== Return Value + +`true` if the left object is greater than or equal to the right object, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *lhs* +| The left operand +| *rhs* +| The right operand +|=== + +[#operator_3way] +== operator<=> + +Three‐way comparison operator + +=== Synopsis + +Declared in `<returns‐from‐special.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +auto +operator<=>( + <> const& lhs, + <> const& rhs); +---- + +=== Return Value + +The relative order of the objects + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *lhs* +| The left operand +| *rhs* +| The right operand +|=== + + +[.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/test-files/golden-tests/config/auto-function-metadata/returns-from-special.cpp b/test-files/golden-tests/config/auto-function-metadata/returns-from-special.cpp new file mode 100644 index 000000000..1dbf33008 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/returns-from-special.cpp @@ -0,0 +1,78 @@ +/// A helper class +struct A {}; + +bool +operator==(A const&, A const&); + +bool +operator!=(A const&, A const&); + +bool +operator<(A const&, A const&); + +bool +operator<=(A const&, A const&); + +bool +operator>(A const&, A const&); + +bool +operator>=(A const&, A const&); + +bool +operator!(A const&); + +auto +operator<=>(A const&, A const&); + +struct Undoc {}; + +/// Test class +struct X +{ + operator A() const; + + operator Undoc() const; + + X& + operator=(A const&); + + X&& + operator=(A&&); + + X + operator+(X const&) const; + + X* + operator->(); + + bool + operator==(X const&) const; + + bool + operator!=(X const&) const; + + bool + operator<(X const&) const; + + bool + operator<=(X const&) const; + + bool + operator>(X const&) const; + + bool + operator>=(X const&) const; + + bool + operator!() const; + + auto + operator<=>(X const&) const; +}; + +/// A fake output stream +struct ostream; + +ostream& +operator<<(ostream&, A const&); diff --git a/test-files/golden-tests/config/auto-function-metadata/returns-from-special.html b/test-files/golden-tests/config/auto-function-metadata/returns-from-special.html new file mode 100644 index 000000000..154877617 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/returns-from-special.html @@ -0,0 +1,1116 @@ + + +Reference + + +
+

Reference

+
+
+

Global namespace

+
+

Types

+ + + + + + + + + + + + + + +
NameDescription
A A helper class
Undoc
X Test class
ostream A fake output stream
+ +

Functions

+ + + + + + + + + + + + + + + + + + + +
NameDescription
operator<< Stream insertion operator
operator! Negation operator
operator== Equality operator
operator!= Inequality operator
operator< Less-than operator
operator<= Less-than-or-equal operator
operator> Greater-than operator
operator>= Greater-than-or-equal operator
operator<=> Three-way comparison operator
+ +
+
+
+

A

+
+A helper class + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+struct A;
+
+
+
+ + +
+
+
+

Undoc

+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+struct Undoc;
+
+
+
+ + +
+
+
+

X

+
+Test class + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+struct X;
+
+
+
+

Member Functions

+ + + + + + + + + + + + + + + + + + + + + + + +
NameDescription
operator= Assignment operators
operator+ Addition operator
operator-> Member access operator
operator A Conversion to A
operator Undoc Conversion to Undoc
operator! Negation operator
operator== Equality operator
operator!= Inequality operator
operator< Less-than operator
operator<= Less-than-or-equal operator
operator> Greater-than operator
operator>= Greater-than-or-equal operator
operator<=> Three-way comparison operator
+ + + +
+
+
+

X::operator=

+
+Assignment operators + +
+
+
+

Synopses

+
+Declared in <returns-from-special.cpp>
+Assignment operator +
+
+X&
+operator=(A const& value);
+
+
» more... + +Assignment operator +
+
+X&&
+operator=(A&& value);
+
+
» more... + + +
+
+
+
+

X::operator=

+
+Assignment operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+X&
+operator=(A const& value);
+
+
+
+
+

Return Value

+Reference to the current object +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
valueThe object to copy assign from
+
+
+
+
+

X::operator=

+
+Assignment operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+X&&
+operator=(A&& value);
+
+
+
+
+

Return Value

+Rvalue reference to the current object +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
valueThe object to move assign from
+
+
+
+
+

X::operator+

+
+Addition operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+X
+operator+(X const& rhs) const;
+
+
+
+
+

Return Value

+Another instance of the object +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
rhsThe right operand
+
+
+
+
+

X::operator->

+
+Member access operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+X*
+operator->();
+
+
+
+
+

Return Value

+Pointer to the current object +
+
+
+
+

X::operator A

+
+Conversion to A + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+operator A() const;
+
+
+
+
+

Return Value

+A helper class +
+
+
+
+

X::operator Undoc

+
+Conversion to Undoc + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+operator Undoc() const;
+
+
+
+
+

Return Value

+The object converted to Undoc +
+
+
+
+

X::operator!

+
+Negation operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+bool
+operator!() const;
+
+
+
+
+

Return Value

+true if the object is falsy, false otherwise +
+
+
+
+

X::operator==

+
+Equality operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+bool
+operator==(X const& rhs) const;
+
+
+
+
+

Return Value

+true if the objects are equal, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
rhsThe right operand
+
+
+
+
+

X::operator!=

+
+Inequality operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+bool
+operator!=(X const& rhs) const;
+
+
+
+
+

Return Value

+true if the objects are not equal, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
rhsThe right operand
+
+
+
+
+

X::operator<

+
+Less-than operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+bool
+operator<(X const& rhs) const;
+
+
+
+
+

Return Value

+true if the left object is less than the right object, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
rhsThe right operand
+
+
+
+
+

X::operator<=

+
+Less-than-or-equal operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+bool
+operator<=(X const& rhs) const;
+
+
+
+
+

Return Value

+true if the left object is less than or equal to the right object, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
rhsThe right operand
+
+
+
+
+

X::operator>

+
+Greater-than operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+bool
+operator>(X const& rhs) const;
+
+
+
+
+

Return Value

+true if the left object is greater than the right object, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
rhsThe right operand
+
+
+
+
+

X::operator>=

+
+Greater-than-or-equal operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+bool
+operator>=(X const& rhs) const;
+
+
+
+
+

Return Value

+true if the left object is greater than or equal to the right object, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
rhsThe right operand
+
+
+
+
+

X::operator<=>

+
+Three-way comparison operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+auto
+operator<=>(X const& rhs) const;
+
+
+
+
+

Return Value

+The relative order of the objects +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
rhsThe right operand
+
+
+
+
+

ostream

+
+A fake output stream + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+struct ostream;
+
+
+
+ + +
+
+
+

operator<<

+
+Stream insertion operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+ostream&
+operator<<(
+    ostream& os,
+    A const& value);
+
+
+
+
+

Return Value

+Reference to the current output stream +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
osAn output stream
valueThe object to output
+
+
+
+
+

operator!

+
+Negation operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+bool
+operator!(A const& value);
+
+
+
+
+

Return Value

+true if the object is falsy, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
valueThe operand
+
+
+
+
+

operator==

+
+Equality operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+bool
+operator==(
+    A const& lhs,
+    A const& rhs);
+
+
+
+
+

Return Value

+true if the objects are equal, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
lhsThe left operand
rhsThe right operand
+
+
+
+
+

operator!=

+
+Inequality operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+bool
+operator!=(
+    A const& lhs,
+    A const& rhs);
+
+
+
+
+

Return Value

+true if the objects are not equal, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
lhsThe left operand
rhsThe right operand
+
+
+
+
+

operator<

+
+Less-than operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+bool
+operator<(
+    A const& lhs,
+    A const& rhs);
+
+
+
+
+

Return Value

+true if the left object is less than the right object, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
lhsThe left operand
rhsThe right operand
+
+
+
+
+

operator<=

+
+Less-than-or-equal operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+bool
+operator<=(
+    A const& lhs,
+    A const& rhs);
+
+
+
+
+

Return Value

+true if the left object is less than or equal to the right object, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
lhsThe left operand
rhsThe right operand
+
+
+
+
+

operator>

+
+Greater-than operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+bool
+operator>(
+    A const& lhs,
+    A const& rhs);
+
+
+
+
+

Return Value

+true if the left object is greater than the right object, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
lhsThe left operand
rhsThe right operand
+
+
+
+
+

operator>=

+
+Greater-than-or-equal operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+bool
+operator>=(
+    A const& lhs,
+    A const& rhs);
+
+
+
+
+

Return Value

+true if the left object is greater than or equal to the right object, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
lhsThe left operand
rhsThe right operand
+
+
+
+
+

operator<=>

+
+Three-way comparison operator + +
+
+
+

Synopsis

+
+Declared in <returns-from-special.cpp>
+
+
+auto
+operator<=>(
+    A const& lhs,
+    A const& rhs);
+
+
+
+
+

Return Value

+The relative order of the objects +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
lhsThe left operand
rhsThe right operand
+
+
+ +
+
+

Created with MrDocs

+
+ + \ No newline at end of file diff --git a/test-files/golden-tests/config/auto-function-metadata/returns-from-special.xml b/test-files/golden-tests/config/auto-function-metadata/returns-from-special.xml new file mode 100644 index 000000000..91b8ee830 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/returns-from-special.xml @@ -0,0 +1,658 @@ + + + + + + + + A helper class + + + + + + + + + + + Test class + + + + + + + + + + + + + + + + + + Assignment operator + + + Reference to the current object + + + The object to copy assign from + + + + + + + + + + + + + + + + + + + Assignment operator + + + Rvalue reference to the current object + + + The object to move assign from + + + + + + + + + + + + + + + + + + Addition operator + + + Another instance of the object + + + The right operand + + + + + + + + + + + + + + Member access operator + + + Pointer to the current object + + + + + + + + + + + + Conversion to + A + + + A helper class + + + + + + + + + + + + Conversion to + Undoc + + + The object converted to + Undoc + + + + + + + + + + + + + Negation operator + + + true + if the object is falsy, + false + otherwise + + + + + + + + + + + + + + + + + + Equality operator + + + true + if the objects are equal, + false + otherwise + + + The right operand + + + + + + + + + + + + + + + + + + Inequality operator + + + true + if the objects are not equal, + false + otherwise + + + The right operand + + + + + + + + + + + + + + + + + + Less-than operator + + + true + if the left object is less than the right object, + false + otherwise + + + The right operand + + + + + + + + + + + + + + + + + + Less-than-or-equal operator + + + true + if the left object is less than or equal to the right object, + false + otherwise + + + The right operand + + + + + + + + + + + + + + + + + + Greater-than operator + + + true + if the left object is greater than the right object, + false + otherwise + + + The right operand + + + + + + + + + + + + + + + + + + Greater-than-or-equal operator + + + true + if the left object is greater than or equal to the right object, + false + otherwise + + + The right operand + + + + + + + + + + + + + + + + + + + Three-way comparison operator + + + The relative order of the objects + + + The right operand + + + + + + + + + A fake output stream + + + + + + + + + + + + + + + + + + + + + + + + Stream insertion operator + + + Reference to the current output stream + + + An output stream + + + The object to output + + + + + + + + + + + + + + + + + Negation operator + + + true + if the object is falsy, + false + otherwise + + + The operand + + + + + + + + + + + + + + + + + + + + + + Equality operator + + + true + if the objects are equal, + false + otherwise + + + The left operand + + + The right operand + + + + + + + + + + + + + + + + + + + + + + Inequality operator + + + true + if the objects are not equal, + false + otherwise + + + The left operand + + + The right operand + + + + + + + + + + + + + + + + + + + + + + Less-than operator + + + true + if the left object is less than the right object, + false + otherwise + + + The left operand + + + The right operand + + + + + + + + + + + + + + + + + + + + + + Less-than-or-equal operator + + + true + if the left object is less than or equal to the right object, + false + otherwise + + + The left operand + + + The right operand + + + + + + + + + + + + + + + + + + + + + + Greater-than operator + + + true + if the left object is greater than the right object, + false + otherwise + + + The left operand + + + The right operand + + + + + + + + + + + + + + + + + + + + + + Greater-than-or-equal operator + + + true + if the left object is greater than or equal to the right object, + false + otherwise + + + The left operand + + + The right operand + + + + + + + + + + + + + + + + + + + + + + + Three-way comparison operator + + + The relative order of the objects + + + The left operand + + + The right operand + + + + + diff --git a/test-files/golden-tests/config/auto-function-metadata/returns-from-special.yml b/test-files/golden-tests/config/auto-function-metadata/returns-from-special.yml new file mode 100644 index 000000000..2bdf9b1c4 --- /dev/null +++ b/test-files/golden-tests/config/auto-function-metadata/returns-from-special.yml @@ -0,0 +1 @@ +auto-function-metadata: true \ No newline at end of file diff --git a/test-files/golden-tests/config/inherit-base-members/copy-dependencies.adoc b/test-files/golden-tests/config/inherit-base-members/copy-dependencies.adoc index 0b3546a15..698cae068 100644 --- a/test-files/golden-tests/config/inherit-base-members/copy-dependencies.adoc +++ b/test-files/golden-tests/config/inherit-base-members/copy-dependencies.adoc @@ -11,20 +11,22 @@ | Name | Description | <> -| +| A base class to test inheritance and shadowing | <> -| +| A second‐order base class to test indirect inheritance | <> -| +| A class that derives from base and excluded_base | <> -| +| A class that uses private inheritance only | <> -| Should inherit functions as protected. +| A class that should inherit functions as protected. |=== [#base] == base +A base class to test inheritance and shadowing + === Synopsis Declared in `<copy‐dependencies.cpp>` @@ -42,7 +44,7 @@ class base | Name | Description | `<>` -| +| A second‐order base class to test indirect inheritance |=== === Member Functions @@ -84,7 +86,7 @@ class base | Name | Description | <> -| +| A class that derives from base and excluded_base |=== [#base-base_inherited] @@ -102,6 +104,10 @@ Declared in `<copy‐dependencies.cpp>` base_inherited(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-base_shadowed] == <>::base_shadowed @@ -117,6 +123,10 @@ Declared in `<copy‐dependencies.cpp>` base_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-derived_shadowed] == <>::derived_shadowed @@ -132,6 +142,10 @@ Declared in `<copy‐dependencies.cpp>` derived_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-do_base_inherited] == <>::do_base_inherited @@ -147,6 +161,10 @@ Declared in `<copy‐dependencies.cpp>` do_base_inherited(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-do_base_shadowed] == <>::do_base_shadowed @@ -162,6 +180,10 @@ Declared in `<copy‐dependencies.cpp>` do_base_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-do_derived_shadowed] == <>::do_derived_shadowed @@ -177,9 +199,15 @@ Declared in `<copy‐dependencies.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base_base] == base_base +A second‐order base class to test indirect inheritance + === Synopsis Declared in `<copy‐dependencies.cpp>` @@ -208,7 +236,7 @@ class base_base; | Name | Description | <> -| +| A base class to test inheritance and shadowing |=== [#base_base-base_base_inherited] @@ -226,6 +254,10 @@ Declared in `<copy‐dependencies.cpp>` base_base_inherited(); ---- +=== Return Value + +A second‐order base class to test indirect inheritance + [#base_base-do_base_base_inherited] == <>::do_base_base_inherited @@ -241,9 +273,15 @@ Declared in `<copy‐dependencies.cpp>` do_base_base_inherited(); ---- +=== Return Value + +A second‐order base class to test indirect inheritance + [#derived] == derived +A class that derives from base and excluded_base + === Synopsis Declared in `<copy‐dependencies.cpp>` @@ -262,7 +300,7 @@ class derived | Name | Description | `<>` -| +| A base class to test inheritance and shadowing | `excluded_base` | |=== @@ -322,6 +360,10 @@ Declared in `<copy‐dependencies.cpp>` derived_shadowed(); ---- +=== Return Value + +A class that derives from base and excluded_base + [#derived-do_derived_shadowed] == <>::do_derived_shadowed @@ -337,6 +379,10 @@ Declared in `<copy‐dependencies.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A class that derives from base and excluded_base + [#derived-excluded_inherited] == <>::excluded_inherited @@ -385,6 +431,8 @@ do_shadowed(); [#private_derived] == private_derived +A class that uses private inheritance only + === Synopsis Declared in `<copy‐dependencies.cpp>` @@ -423,6 +471,10 @@ Declared in `<copy‐dependencies.cpp>` derived_shadowed(); ---- +=== Return Value + +A class that uses private inheritance only + [#private_derived-do_derived_shadowed] == <>::do_derived_shadowed @@ -438,10 +490,14 @@ Declared in `<copy‐dependencies.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A class that uses private inheritance only + [#protected_derived] == protected_derived -Should inherit functions as protected. +A class that should inherit functions as protected. === Synopsis @@ -511,6 +567,10 @@ Declared in `<copy‐dependencies.cpp>` derived_shadowed(); ---- +=== Return Value + +A class that should inherit functions as protected. + [#protected_derived-do_derived_shadowed] == <>::do_derived_shadowed @@ -526,6 +586,10 @@ Declared in `<copy‐dependencies.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A class that should inherit functions as protected. + [#protected_derived-do_excluded_inherited] == <>::do_excluded_inherited diff --git a/test-files/golden-tests/config/inherit-base-members/copy-dependencies.cpp b/test-files/golden-tests/config/inherit-base-members/copy-dependencies.cpp index ae1d15ebe..eff6deaf5 100644 --- a/test-files/golden-tests/config/inherit-base-members/copy-dependencies.cpp +++ b/test-files/golden-tests/config/inherit-base-members/copy-dependencies.cpp @@ -1,3 +1,4 @@ +/// A base class excluded from the documentation class excluded_base { public: /// This function should be shadowed by derived classes. @@ -15,6 +16,7 @@ class excluded_base { excluded_base& do_excluded_inherited(); }; +/// A second-order base class to test indirect inheritance class base_base { public: /// This function should be indirectly inherited by derived classes. @@ -24,6 +26,7 @@ class base_base { base_base& do_base_base_inherited(); }; +/// A base class to test inheritance and shadowing class base : public base_base { @@ -43,6 +46,7 @@ class base : base& do_base_inherited(); }; +/// A class that derives from base and excluded_base class derived : public base , public excluded_base @@ -55,7 +59,7 @@ class derived derived& do_derived_shadowed(); }; -/// Should inherit functions as protected. +/// A class that should inherit functions as protected. class protected_derived : protected base , protected excluded_base @@ -68,6 +72,7 @@ class protected_derived protected_derived& do_derived_shadowed(); }; +/// A class that uses private inheritance only class private_derived : private base , private excluded_base diff --git a/test-files/golden-tests/config/inherit-base-members/copy-dependencies.html b/test-files/golden-tests/config/inherit-base-members/copy-dependencies.html index d72f94210..6f14d2483 100644 --- a/test-files/golden-tests/config/inherit-base-members/copy-dependencies.html +++ b/test-files/golden-tests/config/inherit-base-members/copy-dependencies.html @@ -19,11 +19,11 @@

Types

-base -base_base -derived -private_derived -protected_derived Should inherit functions as protected. +base A base class to test inheritance and shadowing +base_base A second-order base class to test indirect inheritance +derived A class that derives from base and excluded_base +private_derived A class that uses private inheritance only +protected_derived A class that should inherit functions as protected. @@ -31,6 +31,10 @@

Types

base

+
+A base class to test inheritance and shadowing + +

Synopsis

@@ -53,7 +57,7 @@

Base Classes

-base_base +base_baseA second-order base class to test indirect inheritance
@@ -104,7 +108,7 @@

Derived Classes

derived - + A class that derives from base and excluded_base
@@ -128,6 +132,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -148,6 +156,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -168,6 +180,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -188,6 +204,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -208,6 +228,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -228,10 +252,18 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +

base_base

+
+A second-order base class to test indirect inheritance + +

Synopsis

@@ -271,7 +303,7 @@

Derived Classes

base - + A base class to test inheritance and shadowing
@@ -295,6 +327,10 @@

Synopsis

+
+

Return Value

+A second-order base class to test indirect inheritance +
@@ -315,10 +351,18 @@

Synopsis

+
+

Return Value

+A second-order base class to test indirect inheritance +

derived

+
+A class that derives from base and excluded_base + +

Synopsis

@@ -342,7 +386,7 @@

Base Classes

-base +baseA base class to test inheritance and shadowing excluded_base @@ -407,6 +451,10 @@

Synopsis

+
+

Return Value

+A class that derives from base and excluded_base +
@@ -427,6 +475,10 @@

Synopsis

+
+

Return Value

+A class that derives from base and excluded_base +
@@ -491,6 +543,10 @@

Synopsis

private_derived

+
+A class that uses private inheritance only + +

Synopsis

@@ -541,6 +597,10 @@

Synopsis

+
+

Return Value

+A class that uses private inheritance only +
@@ -561,12 +621,16 @@

Synopsis

+
+

Return Value

+A class that uses private inheritance only +

protected_derived

-Should inherit functions as protected. +A class that should inherit functions as protected.
@@ -643,6 +707,10 @@

Synopsis

+
+

Return Value

+A class that should inherit functions as protected. +
@@ -663,6 +731,10 @@

Synopsis

+
+

Return Value

+A class that should inherit functions as protected. +
diff --git a/test-files/golden-tests/config/inherit-base-members/copy-dependencies.xml b/test-files/golden-tests/config/inherit-base-members/copy-dependencies.xml index cc3aff253..518a2a8f4 100644 --- a/test-files/golden-tests/config/inherit-base-members/copy-dependencies.xml +++ b/test-files/golden-tests/config/inherit-base-members/copy-dependencies.xml @@ -3,12 +3,17 @@ xsi:noNamespaceSchemaLocation="https://github.com/cppalliance/mrdocs/raw/develop/mrdocs.rnc"> - + + + + A base class to test inheritance and shadowing + + - + @@ -18,10 +23,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -31,10 +39,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -44,10 +55,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -57,10 +71,13 @@ This function should be shadowed by derived classes. + + A base class to test inheritance and shadowing + - + @@ -70,10 +87,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -83,10 +103,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -96,10 +119,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -109,13 +135,21 @@ This function should be shadowed by derived classes. + + A base class to test inheritance and shadowing + - + + + + A second-order base class to test indirect inheritance + + - + @@ -125,10 +159,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -138,19 +175,27 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + + + + A class that derives from base and excluded_base + + - + @@ -160,10 +205,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -173,10 +221,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -186,10 +237,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -199,10 +253,13 @@ This function should shadow the base class function. + + A class that derives from base and excluded_base + - + @@ -212,10 +269,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -225,10 +285,13 @@ This function should shadow the base class function. + + A class that derives from base and excluded_base + - + @@ -241,7 +304,7 @@ - + @@ -251,10 +314,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -264,10 +330,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -277,10 +346,13 @@ This function should be shadowed by derived classes. + + A base class to test inheritance and shadowing + - + @@ -293,7 +365,7 @@ - + @@ -307,15 +379,20 @@ - + + + + A class that uses private inheritance only + + - + @@ -325,10 +402,13 @@ This function should shadow the base class function. + + A class that uses private inheritance only + - + @@ -338,11 +418,14 @@ This function should shadow the base class function. + + A class that uses private inheritance only + - + @@ -351,11 +434,11 @@ - Should inherit functions as protected. + A class that should inherit functions as protected. - + @@ -365,10 +448,13 @@ This function should shadow the base class function. + + A class that should inherit functions as protected. + - + @@ -378,10 +464,13 @@ This function should shadow the base class function. + + A class that should inherit functions as protected. + - + @@ -391,10 +480,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -404,10 +496,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -417,10 +512,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -430,10 +528,13 @@ This function should be shadowed by derived classes. + + A base class to test inheritance and shadowing + - + @@ -443,10 +544,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -456,10 +560,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -469,10 +576,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -482,10 +592,13 @@ This function should be shadowed by derived classes. + + A base class to test inheritance and shadowing + - + @@ -498,7 +611,7 @@ - + @@ -511,7 +624,7 @@ - + diff --git a/test-files/golden-tests/config/inherit-base-members/copy.adoc b/test-files/golden-tests/config/inherit-base-members/copy.adoc index 18b4293c1..bdc5685b4 100644 --- a/test-files/golden-tests/config/inherit-base-members/copy.adoc +++ b/test-files/golden-tests/config/inherit-base-members/copy.adoc @@ -11,20 +11,22 @@ | Name | Description | <> -| +| A base class to test inheritance and shadowing | <> -| +| A second‐order base class to test indirect inheritance | <> -| +| A class that derives from base and excluded_base | <> -| +| A class that uses private inheritance only | <> -| Should inherit functions as protected. +| A class that should inherit functions as protected. |=== [#base] == base +A base class to test inheritance and shadowing + === Synopsis Declared in `<copy.cpp>` @@ -42,7 +44,7 @@ class base | Name | Description | `<>` -| +| A second‐order base class to test indirect inheritance |=== === Member Functions @@ -84,7 +86,7 @@ class base | Name | Description | <> -| +| A class that derives from base and excluded_base |=== [#base-base_base_inherited] @@ -102,6 +104,10 @@ Declared in `<copy.cpp>` base_base_inherited(); ---- +=== Return Value + +A second‐order base class to test indirect inheritance + [#base-base_inherited] == <>::base_inherited @@ -117,6 +123,10 @@ Declared in `<copy.cpp>` base_inherited(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-base_shadowed] == <>::base_shadowed @@ -132,6 +142,10 @@ Declared in `<copy.cpp>` base_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-derived_shadowed] == <>::derived_shadowed @@ -147,6 +161,10 @@ Declared in `<copy.cpp>` derived_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-do_base_base_inherited] == <>::do_base_base_inherited @@ -162,6 +180,10 @@ Declared in `<copy.cpp>` do_base_base_inherited(); ---- +=== Return Value + +A second‐order base class to test indirect inheritance + [#base-do_base_inherited] == <>::do_base_inherited @@ -177,6 +199,10 @@ Declared in `<copy.cpp>` do_base_inherited(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-do_base_shadowed] == <>::do_base_shadowed @@ -192,6 +218,10 @@ Declared in `<copy.cpp>` do_base_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-do_derived_shadowed] == <>::do_derived_shadowed @@ -207,9 +237,15 @@ Declared in `<copy.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base_base] == base_base +A second‐order base class to test indirect inheritance + === Synopsis Declared in `<copy.cpp>` @@ -238,7 +274,7 @@ class base_base; | Name | Description | <> -| +| A base class to test inheritance and shadowing |=== [#base_base-base_base_inherited] @@ -256,6 +292,10 @@ Declared in `<copy.cpp>` base_base_inherited(); ---- +=== Return Value + +A second‐order base class to test indirect inheritance + [#base_base-do_base_base_inherited] == <>::do_base_base_inherited @@ -271,9 +311,15 @@ Declared in `<copy.cpp>` do_base_base_inherited(); ---- +=== Return Value + +A second‐order base class to test indirect inheritance + [#derived] == derived +A class that derives from base and excluded_base + === Synopsis Declared in `<copy.cpp>` @@ -292,7 +338,7 @@ class derived | Name | Description | `<>` -| +| A base class to test inheritance and shadowing | `excluded_base` | |=== @@ -352,6 +398,10 @@ Declared in `<copy.cpp>` base_base_inherited(); ---- +=== Return Value + +A second‐order base class to test indirect inheritance + [#derived-base_inherited] == <>::base_inherited @@ -367,6 +417,10 @@ Declared in `<copy.cpp>` base_inherited(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#derived-base_shadowed] == <>::base_shadowed @@ -382,6 +436,10 @@ Declared in `<copy.cpp>` base_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#derived-derived_shadowed] == <>::derived_shadowed @@ -397,6 +455,10 @@ Declared in `<copy.cpp>` derived_shadowed(); ---- +=== Return Value + +A class that derives from base and excluded_base + [#derived-do_base_base_inherited] == <>::do_base_base_inherited @@ -412,6 +474,10 @@ Declared in `<copy.cpp>` do_base_base_inherited(); ---- +=== Return Value + +A second‐order base class to test indirect inheritance + [#derived-do_derived_shadowed-0a] == <>::do_derived_shadowed @@ -427,6 +493,10 @@ Declared in `<copy.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A class that derives from base and excluded_base + [#derived-excluded_inherited] == <>::excluded_inherited @@ -457,6 +527,10 @@ Declared in `<copy.cpp>` do_base_inherited(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#derived-do_base_shadowed] == <>::do_base_shadowed @@ -472,6 +546,10 @@ Declared in `<copy.cpp>` do_base_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#derived-do_derived_shadowed-0d] == <>::do_derived_shadowed @@ -487,6 +565,10 @@ Declared in `<copy.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#derived-do_excluded_inherited] == <>::do_excluded_inherited @@ -520,6 +602,8 @@ do_shadowed(); [#private_derived] == private_derived +A class that uses private inheritance only + === Synopsis Declared in `<copy.cpp>` @@ -558,6 +642,10 @@ Declared in `<copy.cpp>` derived_shadowed(); ---- +=== Return Value + +A class that uses private inheritance only + [#private_derived-do_derived_shadowed] == <>::do_derived_shadowed @@ -573,10 +661,14 @@ Declared in `<copy.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A class that uses private inheritance only + [#protected_derived] == protected_derived -Should inherit functions as protected. +A class that should inherit functions as protected. === Synopsis @@ -646,6 +738,10 @@ Declared in `<copy.cpp>` derived_shadowed(); ---- +=== Return Value + +A class that should inherit functions as protected. + [#protected_derived-do_derived_shadowed-0e] == <>::do_derived_shadowed @@ -661,6 +757,10 @@ Declared in `<copy.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A class that should inherit functions as protected. + [#protected_derived-base_base_inherited] == <>::base_base_inherited @@ -676,6 +776,10 @@ Declared in `<copy.cpp>` base_base_inherited(); ---- +=== Return Value + +A second‐order base class to test indirect inheritance + [#protected_derived-base_inherited] == <>::base_inherited @@ -691,6 +795,10 @@ Declared in `<copy.cpp>` base_inherited(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#protected_derived-base_shadowed] == <>::base_shadowed @@ -706,6 +814,10 @@ Declared in `<copy.cpp>` base_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#protected_derived-derived_shadowed-0f] == <>::derived_shadowed @@ -721,6 +833,10 @@ Declared in `<copy.cpp>` derived_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#protected_derived-do_base_base_inherited] == <>::do_base_base_inherited @@ -736,6 +852,10 @@ Declared in `<copy.cpp>` do_base_base_inherited(); ---- +=== Return Value + +A second‐order base class to test indirect inheritance + [#protected_derived-do_base_inherited] == <>::do_base_inherited @@ -751,6 +871,10 @@ Declared in `<copy.cpp>` do_base_inherited(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#protected_derived-do_base_shadowed] == <>::do_base_shadowed @@ -766,6 +890,10 @@ Declared in `<copy.cpp>` do_base_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#protected_derived-do_derived_shadowed-06] == <>::do_derived_shadowed @@ -781,6 +909,10 @@ Declared in `<copy.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#protected_derived-do_excluded_inherited] == <>::do_excluded_inherited diff --git a/test-files/golden-tests/config/inherit-base-members/copy.cpp b/test-files/golden-tests/config/inherit-base-members/copy.cpp index ae1d15ebe..eff6deaf5 100644 --- a/test-files/golden-tests/config/inherit-base-members/copy.cpp +++ b/test-files/golden-tests/config/inherit-base-members/copy.cpp @@ -1,3 +1,4 @@ +/// A base class excluded from the documentation class excluded_base { public: /// This function should be shadowed by derived classes. @@ -15,6 +16,7 @@ class excluded_base { excluded_base& do_excluded_inherited(); }; +/// A second-order base class to test indirect inheritance class base_base { public: /// This function should be indirectly inherited by derived classes. @@ -24,6 +26,7 @@ class base_base { base_base& do_base_base_inherited(); }; +/// A base class to test inheritance and shadowing class base : public base_base { @@ -43,6 +46,7 @@ class base : base& do_base_inherited(); }; +/// A class that derives from base and excluded_base class derived : public base , public excluded_base @@ -55,7 +59,7 @@ class derived derived& do_derived_shadowed(); }; -/// Should inherit functions as protected. +/// A class that should inherit functions as protected. class protected_derived : protected base , protected excluded_base @@ -68,6 +72,7 @@ class protected_derived protected_derived& do_derived_shadowed(); }; +/// A class that uses private inheritance only class private_derived : private base , private excluded_base diff --git a/test-files/golden-tests/config/inherit-base-members/copy.html b/test-files/golden-tests/config/inherit-base-members/copy.html index ed2bff1f4..b56b7845a 100644 --- a/test-files/golden-tests/config/inherit-base-members/copy.html +++ b/test-files/golden-tests/config/inherit-base-members/copy.html @@ -19,11 +19,11 @@

Types

-base -base_base -derived -private_derived -protected_derived Should inherit functions as protected. +base A base class to test inheritance and shadowing +base_base A second-order base class to test indirect inheritance +derived A class that derives from base and excluded_base +private_derived A class that uses private inheritance only +protected_derived A class that should inherit functions as protected. @@ -31,6 +31,10 @@

Types

base

+
+A base class to test inheritance and shadowing + +

Synopsis

@@ -53,7 +57,7 @@

Base Classes

-base_base +base_baseA second-order base class to test indirect inheritance
@@ -104,7 +108,7 @@

Derived Classes

derived - + A class that derives from base and excluded_base
@@ -128,6 +132,10 @@

Synopsis

+
+

Return Value

+A second-order base class to test indirect inheritance +
@@ -148,6 +156,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -168,6 +180,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -188,6 +204,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -208,6 +228,10 @@

Synopsis

+
+

Return Value

+A second-order base class to test indirect inheritance +
@@ -228,6 +252,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -248,6 +276,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -268,10 +300,18 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +

base_base

+
+A second-order base class to test indirect inheritance + +

Synopsis

@@ -311,7 +351,7 @@

Derived Classes

base - + A base class to test inheritance and shadowing
@@ -335,6 +375,10 @@

Synopsis

+
+

Return Value

+A second-order base class to test indirect inheritance +
@@ -355,10 +399,18 @@

Synopsis

+
+

Return Value

+A second-order base class to test indirect inheritance +

derived

+
+A class that derives from base and excluded_base + +

Synopsis

@@ -382,7 +434,7 @@

Base Classes

-base +baseA base class to test inheritance and shadowing excluded_base @@ -447,6 +499,10 @@

Synopsis

+
+

Return Value

+A second-order base class to test indirect inheritance +
@@ -467,6 +523,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -487,6 +547,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -507,6 +571,10 @@

Synopsis

+
+

Return Value

+A class that derives from base and excluded_base +
@@ -527,6 +595,10 @@

Synopsis

+
+

Return Value

+A second-order base class to test indirect inheritance +
@@ -547,6 +619,10 @@

Synopsis

+
+

Return Value

+A class that derives from base and excluded_base +
@@ -587,6 +663,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -607,6 +687,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -627,6 +711,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -671,6 +759,10 @@

Synopsis

private_derived

+
+A class that uses private inheritance only + +

Synopsis

@@ -721,6 +813,10 @@

Synopsis

+
+

Return Value

+A class that uses private inheritance only +
@@ -741,12 +837,16 @@

Synopsis

+
+

Return Value

+A class that uses private inheritance only +

protected_derived

-Should inherit functions as protected. +A class that should inherit functions as protected.
@@ -823,6 +923,10 @@

Synopsis

+
+

Return Value

+A class that should inherit functions as protected. +
@@ -843,6 +947,10 @@

Synopsis

+
+

Return Value

+A class that should inherit functions as protected. +
@@ -863,6 +971,10 @@

Synopsis

+
+

Return Value

+A second-order base class to test indirect inheritance +
@@ -883,6 +995,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -903,6 +1019,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -923,6 +1043,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -943,6 +1067,10 @@

Synopsis

+
+

Return Value

+A second-order base class to test indirect inheritance +
@@ -963,6 +1091,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -983,6 +1115,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -1003,6 +1139,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
diff --git a/test-files/golden-tests/config/inherit-base-members/copy.xml b/test-files/golden-tests/config/inherit-base-members/copy.xml index e077a4aaa..e2a9fdb77 100644 --- a/test-files/golden-tests/config/inherit-base-members/copy.xml +++ b/test-files/golden-tests/config/inherit-base-members/copy.xml @@ -3,12 +3,17 @@ xsi:noNamespaceSchemaLocation="https://github.com/cppalliance/mrdocs/raw/develop/mrdocs.rnc"> - + + + + A base class to test inheritance and shadowing + + - + @@ -18,10 +23,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -31,10 +39,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -44,10 +55,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -57,10 +71,13 @@ This function should be shadowed by derived classes. + + A base class to test inheritance and shadowing + - + @@ -70,10 +87,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -83,10 +103,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -96,10 +119,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -109,13 +135,21 @@ This function should be shadowed by derived classes. + + A base class to test inheritance and shadowing + - + + + + A second-order base class to test indirect inheritance + + - + @@ -125,10 +159,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -138,19 +175,27 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + + + + A class that derives from base and excluded_base + + - + @@ -160,10 +205,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -173,10 +221,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -186,10 +237,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -199,10 +253,13 @@ This function should shadow the base class function. + + A class that derives from base and excluded_base + - + @@ -212,10 +269,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -225,10 +285,13 @@ This function should shadow the base class function. + + A class that derives from base and excluded_base + - + @@ -241,7 +304,7 @@ - + @@ -251,10 +314,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -264,10 +330,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -277,10 +346,13 @@ This function should be shadowed by derived classes. + + A base class to test inheritance and shadowing + - + @@ -293,7 +365,7 @@ - + @@ -307,15 +379,20 @@ - + + + + A class that uses private inheritance only + + - + @@ -325,10 +402,13 @@ This function should shadow the base class function. + + A class that uses private inheritance only + - + @@ -338,11 +418,14 @@ This function should shadow the base class function. + + A class that uses private inheritance only + - + @@ -351,11 +434,11 @@ - Should inherit functions as protected. + A class that should inherit functions as protected. - + @@ -365,10 +448,13 @@ This function should shadow the base class function. + + A class that should inherit functions as protected. + - + @@ -378,10 +464,13 @@ This function should shadow the base class function. + + A class that should inherit functions as protected. + - + @@ -391,10 +480,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -404,10 +496,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -417,10 +512,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -430,10 +528,13 @@ This function should be shadowed by derived classes. + + A base class to test inheritance and shadowing + - + @@ -443,10 +544,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -456,10 +560,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -469,10 +576,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -482,10 +592,13 @@ This function should be shadowed by derived classes. + + A base class to test inheritance and shadowing + - + @@ -498,7 +611,7 @@ - + @@ -511,7 +624,7 @@ - + diff --git a/test-files/golden-tests/config/inherit-base-members/never.adoc b/test-files/golden-tests/config/inherit-base-members/never.adoc index 3dd9af3cf..c812a06c1 100644 --- a/test-files/golden-tests/config/inherit-base-members/never.adoc +++ b/test-files/golden-tests/config/inherit-base-members/never.adoc @@ -11,20 +11,22 @@ | Name | Description | <> -| +| A base class to test inheritance and shadowing | <> -| +| A second‐order base class to test indirect inheritance | <> -| +| A class that derives from base and excluded_base | <> -| +| A class that uses private inheritance only | <> -| Should inherit functions as protected. +| A class that should inherit functions as protected. |=== [#base] == base +A base class to test inheritance and shadowing + === Synopsis Declared in `<never.cpp>` @@ -42,7 +44,7 @@ class base | Name | Description | `<>` -| +| A second‐order base class to test indirect inheritance |=== === Member Functions @@ -80,7 +82,7 @@ class base | Name | Description | <> -| +| A class that derives from base and excluded_base |=== [#base-base_inherited] @@ -98,6 +100,10 @@ Declared in `<never.cpp>` base_inherited(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-base_shadowed] == <>::base_shadowed @@ -113,6 +119,10 @@ Declared in `<never.cpp>` base_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-derived_shadowed] == <>::derived_shadowed @@ -128,6 +138,10 @@ Declared in `<never.cpp>` derived_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-do_base_inherited] == <>::do_base_inherited @@ -143,6 +157,10 @@ Declared in `<never.cpp>` do_base_inherited(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-do_base_shadowed] == <>::do_base_shadowed @@ -158,6 +176,10 @@ Declared in `<never.cpp>` do_base_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-do_derived_shadowed] == <>::do_derived_shadowed @@ -173,9 +195,15 @@ Declared in `<never.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base_base] == base_base +A second‐order base class to test indirect inheritance + === Synopsis Declared in `<never.cpp>` @@ -204,7 +232,7 @@ class base_base; | Name | Description | <> -| +| A base class to test inheritance and shadowing |=== [#base_base-base_base_inherited] @@ -222,6 +250,10 @@ Declared in `<never.cpp>` base_base_inherited(); ---- +=== Return Value + +A second‐order base class to test indirect inheritance + [#base_base-do_base_base_inherited] == <>::do_base_base_inherited @@ -237,9 +269,15 @@ Declared in `<never.cpp>` do_base_base_inherited(); ---- +=== Return Value + +A second‐order base class to test indirect inheritance + [#derived] == derived +A class that derives from base and excluded_base + === Synopsis Declared in `<never.cpp>` @@ -258,7 +296,7 @@ class derived | Name | Description | `<>` -| +| A base class to test inheritance and shadowing | `excluded_base` | |=== @@ -290,6 +328,10 @@ Declared in `<never.cpp>` derived_shadowed(); ---- +=== Return Value + +A class that derives from base and excluded_base + [#derived-do_derived_shadowed] == <>::do_derived_shadowed @@ -305,9 +347,15 @@ Declared in `<never.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A class that derives from base and excluded_base + [#private_derived] == private_derived +A class that uses private inheritance only + === Synopsis Declared in `<never.cpp>` @@ -346,6 +394,10 @@ Declared in `<never.cpp>` derived_shadowed(); ---- +=== Return Value + +A class that uses private inheritance only + [#private_derived-do_derived_shadowed] == <>::do_derived_shadowed @@ -361,10 +413,14 @@ Declared in `<never.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A class that uses private inheritance only + [#protected_derived] == protected_derived -Should inherit functions as protected. +A class that should inherit functions as protected. === Synopsis @@ -404,6 +460,10 @@ Declared in `<never.cpp>` derived_shadowed(); ---- +=== Return Value + +A class that should inherit functions as protected. + [#protected_derived-do_derived_shadowed] == <>::do_derived_shadowed @@ -419,5 +479,9 @@ Declared in `<never.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A class that should inherit functions as protected. + [.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/test-files/golden-tests/config/inherit-base-members/never.cpp b/test-files/golden-tests/config/inherit-base-members/never.cpp index ae1d15ebe..eff6deaf5 100644 --- a/test-files/golden-tests/config/inherit-base-members/never.cpp +++ b/test-files/golden-tests/config/inherit-base-members/never.cpp @@ -1,3 +1,4 @@ +/// A base class excluded from the documentation class excluded_base { public: /// This function should be shadowed by derived classes. @@ -15,6 +16,7 @@ class excluded_base { excluded_base& do_excluded_inherited(); }; +/// A second-order base class to test indirect inheritance class base_base { public: /// This function should be indirectly inherited by derived classes. @@ -24,6 +26,7 @@ class base_base { base_base& do_base_base_inherited(); }; +/// A base class to test inheritance and shadowing class base : public base_base { @@ -43,6 +46,7 @@ class base : base& do_base_inherited(); }; +/// A class that derives from base and excluded_base class derived : public base , public excluded_base @@ -55,7 +59,7 @@ class derived derived& do_derived_shadowed(); }; -/// Should inherit functions as protected. +/// A class that should inherit functions as protected. class protected_derived : protected base , protected excluded_base @@ -68,6 +72,7 @@ class protected_derived protected_derived& do_derived_shadowed(); }; +/// A class that uses private inheritance only class private_derived : private base , private excluded_base diff --git a/test-files/golden-tests/config/inherit-base-members/never.html b/test-files/golden-tests/config/inherit-base-members/never.html index e66d5b6a5..c7317da3b 100644 --- a/test-files/golden-tests/config/inherit-base-members/never.html +++ b/test-files/golden-tests/config/inherit-base-members/never.html @@ -19,11 +19,11 @@

Types

-base -base_base -derived -private_derived -protected_derived Should inherit functions as protected. +base A base class to test inheritance and shadowing +base_base A second-order base class to test indirect inheritance +derived A class that derives from base and excluded_base +private_derived A class that uses private inheritance only +protected_derived A class that should inherit functions as protected. @@ -31,6 +31,10 @@

Types

base

+
+A base class to test inheritance and shadowing + +

Synopsis

@@ -53,7 +57,7 @@

Base Classes

-base_base +base_baseA second-order base class to test indirect inheritance
@@ -102,7 +106,7 @@

Derived Classes

derived - + A class that derives from base and excluded_base
@@ -126,6 +130,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -146,6 +154,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -166,6 +178,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -186,6 +202,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -206,6 +226,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -226,10 +250,18 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +

base_base

+
+A second-order base class to test indirect inheritance + +

Synopsis

@@ -269,7 +301,7 @@

Derived Classes

base - + A base class to test inheritance and shadowing
@@ -293,6 +325,10 @@

Synopsis

+
+

Return Value

+A second-order base class to test indirect inheritance +
@@ -313,10 +349,18 @@

Synopsis

+
+

Return Value

+A second-order base class to test indirect inheritance +

derived

+
+A class that derives from base and excluded_base + +

Synopsis

@@ -340,7 +384,7 @@

Base Classes

-base +baseA base class to test inheritance and shadowing excluded_base @@ -382,6 +426,10 @@

Synopsis

+
+

Return Value

+A class that derives from base and excluded_base +
@@ -402,10 +450,18 @@

Synopsis

+
+

Return Value

+A class that derives from base and excluded_base +

private_derived

+
+A class that uses private inheritance only + +

Synopsis

@@ -456,6 +512,10 @@

Synopsis

+
+

Return Value

+A class that uses private inheritance only +
@@ -476,12 +536,16 @@

Synopsis

+
+

Return Value

+A class that uses private inheritance only +

protected_derived

-Should inherit functions as protected. +A class that should inherit functions as protected.
@@ -534,6 +598,10 @@

Synopsis

+
+

Return Value

+A class that should inherit functions as protected. +
@@ -554,6 +622,10 @@

Synopsis

+
+

Return Value

+A class that should inherit functions as protected. +
diff --git a/test-files/golden-tests/config/inherit-base-members/never.xml b/test-files/golden-tests/config/inherit-base-members/never.xml index 0523a53f0..f34168d4d 100644 --- a/test-files/golden-tests/config/inherit-base-members/never.xml +++ b/test-files/golden-tests/config/inherit-base-members/never.xml @@ -3,12 +3,17 @@ xsi:noNamespaceSchemaLocation="https://github.com/cppalliance/mrdocs/raw/develop/mrdocs.rnc"> - + + + + A base class to test inheritance and shadowing + + - + @@ -18,10 +23,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -31,10 +39,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -44,10 +55,13 @@ This function should be shadowed by derived classes. + + A base class to test inheritance and shadowing + - + @@ -57,10 +71,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -70,10 +87,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -83,13 +103,21 @@ This function should be shadowed by derived classes. + + A base class to test inheritance and shadowing + - + + + + A second-order base class to test indirect inheritance + + - + @@ -99,10 +127,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -112,19 +143,27 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + + + + A class that derives from base and excluded_base + + - + @@ -134,10 +173,13 @@ This function should shadow the base class function. + + A class that derives from base and excluded_base + - + @@ -147,19 +189,27 @@ This function should shadow the base class function. + + A class that derives from base and excluded_base + - + + + + A class that uses private inheritance only + + - + @@ -169,10 +219,13 @@ This function should shadow the base class function. + + A class that uses private inheritance only + - + @@ -182,11 +235,14 @@ This function should shadow the base class function. + + A class that uses private inheritance only + - + @@ -195,11 +251,11 @@ - Should inherit functions as protected. + A class that should inherit functions as protected. - + @@ -209,10 +265,13 @@ This function should shadow the base class function. + + A class that should inherit functions as protected. + - + @@ -222,6 +281,9 @@ This function should shadow the base class function. + + A class that should inherit functions as protected. + diff --git a/test-files/golden-tests/config/inherit-base-members/reference.adoc b/test-files/golden-tests/config/inherit-base-members/reference.adoc index 0a07b572e..6d4a294c1 100644 --- a/test-files/golden-tests/config/inherit-base-members/reference.adoc +++ b/test-files/golden-tests/config/inherit-base-members/reference.adoc @@ -11,20 +11,22 @@ | Name | Description | <> -| +| A base class to test inheritance and shadowing | <> -| +| A second‐order base class to test indirect inheritance | <> -| +| A class that derives from base and excluded_base | <> -| +| A class that uses private inheritance only | <> -| Should inherit functions as protected. +| A class that should inherit functions as protected. |=== [#base] == base +A base class to test inheritance and shadowing + === Synopsis Declared in `<reference.cpp>` @@ -42,7 +44,7 @@ class base | Name | Description | `<>` -| +| A second‐order base class to test indirect inheritance |=== === Member Functions @@ -84,7 +86,7 @@ class base | Name | Description | <> -| +| A class that derives from base and excluded_base |=== [#base-base_inherited] @@ -102,6 +104,10 @@ Declared in `<reference.cpp>` base_inherited(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-base_shadowed] == <>::base_shadowed @@ -117,6 +123,10 @@ Declared in `<reference.cpp>` base_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-derived_shadowed] == <>::derived_shadowed @@ -132,6 +142,10 @@ Declared in `<reference.cpp>` derived_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-do_base_inherited] == <>::do_base_inherited @@ -147,6 +161,10 @@ Declared in `<reference.cpp>` do_base_inherited(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-do_base_shadowed] == <>::do_base_shadowed @@ -162,6 +180,10 @@ Declared in `<reference.cpp>` do_base_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base-do_derived_shadowed] == <>::do_derived_shadowed @@ -177,9 +199,15 @@ Declared in `<reference.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A base class to test inheritance and shadowing + [#base_base] == base_base +A second‐order base class to test indirect inheritance + === Synopsis Declared in `<reference.cpp>` @@ -208,7 +236,7 @@ class base_base; | Name | Description | <> -| +| A base class to test inheritance and shadowing |=== [#base_base-base_base_inherited] @@ -226,6 +254,10 @@ Declared in `<reference.cpp>` base_base_inherited(); ---- +=== Return Value + +A second‐order base class to test indirect inheritance + [#base_base-do_base_base_inherited] == <>::do_base_base_inherited @@ -241,9 +273,15 @@ Declared in `<reference.cpp>` do_base_base_inherited(); ---- +=== Return Value + +A second‐order base class to test indirect inheritance + [#derived] == derived +A class that derives from base and excluded_base + === Synopsis Declared in `<reference.cpp>` @@ -262,7 +300,7 @@ class derived | Name | Description | `<>` -| +| A base class to test inheritance and shadowing | `excluded_base` | |=== @@ -316,6 +354,10 @@ Declared in `<reference.cpp>` derived_shadowed(); ---- +=== Return Value + +A class that derives from base and excluded_base + [#derived-do_derived_shadowed] == <>::do_derived_shadowed @@ -331,9 +373,15 @@ Declared in `<reference.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A class that derives from base and excluded_base + [#private_derived] == private_derived +A class that uses private inheritance only + === Synopsis Declared in `<reference.cpp>` @@ -372,6 +420,10 @@ Declared in `<reference.cpp>` derived_shadowed(); ---- +=== Return Value + +A class that uses private inheritance only + [#private_derived-do_derived_shadowed] == <>::do_derived_shadowed @@ -387,10 +439,14 @@ Declared in `<reference.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A class that uses private inheritance only + [#protected_derived] == protected_derived -Should inherit functions as protected. +A class that should inherit functions as protected. === Synopsis @@ -454,6 +510,10 @@ Declared in `<reference.cpp>` derived_shadowed(); ---- +=== Return Value + +A class that should inherit functions as protected. + [#protected_derived-do_derived_shadowed] == <>::do_derived_shadowed @@ -469,5 +529,9 @@ Declared in `<reference.cpp>` do_derived_shadowed(); ---- +=== Return Value + +A class that should inherit functions as protected. + [.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/test-files/golden-tests/config/inherit-base-members/reference.cpp b/test-files/golden-tests/config/inherit-base-members/reference.cpp index ae1d15ebe..eff6deaf5 100644 --- a/test-files/golden-tests/config/inherit-base-members/reference.cpp +++ b/test-files/golden-tests/config/inherit-base-members/reference.cpp @@ -1,3 +1,4 @@ +/// A base class excluded from the documentation class excluded_base { public: /// This function should be shadowed by derived classes. @@ -15,6 +16,7 @@ class excluded_base { excluded_base& do_excluded_inherited(); }; +/// A second-order base class to test indirect inheritance class base_base { public: /// This function should be indirectly inherited by derived classes. @@ -24,6 +26,7 @@ class base_base { base_base& do_base_base_inherited(); }; +/// A base class to test inheritance and shadowing class base : public base_base { @@ -43,6 +46,7 @@ class base : base& do_base_inherited(); }; +/// A class that derives from base and excluded_base class derived : public base , public excluded_base @@ -55,7 +59,7 @@ class derived derived& do_derived_shadowed(); }; -/// Should inherit functions as protected. +/// A class that should inherit functions as protected. class protected_derived : protected base , protected excluded_base @@ -68,6 +72,7 @@ class protected_derived protected_derived& do_derived_shadowed(); }; +/// A class that uses private inheritance only class private_derived : private base , private excluded_base diff --git a/test-files/golden-tests/config/inherit-base-members/reference.html b/test-files/golden-tests/config/inherit-base-members/reference.html index 6e1fba920..ce813fb7a 100644 --- a/test-files/golden-tests/config/inherit-base-members/reference.html +++ b/test-files/golden-tests/config/inherit-base-members/reference.html @@ -19,11 +19,11 @@

Types

-base -base_base -derived -private_derived -protected_derived Should inherit functions as protected. +base A base class to test inheritance and shadowing +base_base A second-order base class to test indirect inheritance +derived A class that derives from base and excluded_base +private_derived A class that uses private inheritance only +protected_derived A class that should inherit functions as protected. @@ -31,6 +31,10 @@

Types

base

+
+A base class to test inheritance and shadowing + +

Synopsis

@@ -53,7 +57,7 @@

Base Classes

-base_base +base_baseA second-order base class to test indirect inheritance
@@ -104,7 +108,7 @@

Derived Classes

derived - + A class that derives from base and excluded_base
@@ -128,6 +132,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -148,6 +156,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -168,6 +180,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -188,6 +204,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -208,6 +228,10 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +
@@ -228,10 +252,18 @@

Synopsis

+
+

Return Value

+A base class to test inheritance and shadowing +

base_base

+
+A second-order base class to test indirect inheritance + +

Synopsis

@@ -271,7 +303,7 @@

Derived Classes

base - + A base class to test inheritance and shadowing
@@ -295,6 +327,10 @@

Synopsis

+
+

Return Value

+A second-order base class to test indirect inheritance +
@@ -315,10 +351,18 @@

Synopsis

+
+

Return Value

+A second-order base class to test indirect inheritance +

derived

+
+A class that derives from base and excluded_base + +

Synopsis

@@ -342,7 +386,7 @@

Base Classes

-base +baseA base class to test inheritance and shadowing excluded_base @@ -404,6 +448,10 @@

Synopsis

+
+

Return Value

+A class that derives from base and excluded_base +
@@ -424,10 +472,18 @@

Synopsis

+
+

Return Value

+A class that derives from base and excluded_base +

private_derived

+
+A class that uses private inheritance only + +

Synopsis

@@ -478,6 +534,10 @@

Synopsis

+
+

Return Value

+A class that uses private inheritance only +
@@ -498,12 +558,16 @@

Synopsis

+
+

Return Value

+A class that uses private inheritance only +

protected_derived

-Should inherit functions as protected. +A class that should inherit functions as protected.
@@ -577,6 +641,10 @@

Synopsis

+
+

Return Value

+A class that should inherit functions as protected. +
@@ -597,6 +665,10 @@

Synopsis

+
+

Return Value

+A class that should inherit functions as protected. +
diff --git a/test-files/golden-tests/config/inherit-base-members/reference.xml b/test-files/golden-tests/config/inherit-base-members/reference.xml index 57f8ab6e6..6c1d01927 100644 --- a/test-files/golden-tests/config/inherit-base-members/reference.xml +++ b/test-files/golden-tests/config/inherit-base-members/reference.xml @@ -3,12 +3,17 @@ xsi:noNamespaceSchemaLocation="https://github.com/cppalliance/mrdocs/raw/develop/mrdocs.rnc"> - + + + + A base class to test inheritance and shadowing + + - + @@ -18,10 +23,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -31,10 +39,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -44,10 +55,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -57,10 +71,13 @@ This function should be shadowed by derived classes. + + A base class to test inheritance and shadowing + - + @@ -70,10 +87,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -83,10 +103,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -96,10 +119,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -109,13 +135,21 @@ This function should be shadowed by derived classes. + + A base class to test inheritance and shadowing + - + + + + A second-order base class to test indirect inheritance + + - + @@ -125,10 +159,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -138,19 +175,27 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + + + + A class that derives from base and excluded_base + + - + @@ -160,10 +205,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -173,10 +221,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -186,10 +237,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -199,10 +253,13 @@ This function should shadow the base class function. + + A class that derives from base and excluded_base + - + @@ -212,10 +269,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -225,10 +285,13 @@ This function should shadow the base class function. + + A class that derives from base and excluded_base + - + @@ -238,10 +301,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -251,10 +317,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -264,19 +333,27 @@ This function should be shadowed by derived classes. + + A base class to test inheritance and shadowing + - + + + + A class that uses private inheritance only + + - + @@ -286,10 +363,13 @@ This function should shadow the base class function. + + A class that uses private inheritance only + - + @@ -299,11 +379,14 @@ This function should shadow the base class function. + + A class that uses private inheritance only + - + @@ -312,11 +395,11 @@ - Should inherit functions as protected. + A class that should inherit functions as protected. - + @@ -326,10 +409,13 @@ This function should shadow the base class function. + + A class that should inherit functions as protected. + - + @@ -339,10 +425,13 @@ This function should shadow the base class function. + + A class that should inherit functions as protected. + - + @@ -352,10 +441,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -365,10 +457,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -378,10 +473,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -391,10 +489,13 @@ This function should be shadowed by derived classes. + + A base class to test inheritance and shadowing + - + @@ -404,10 +505,13 @@ This function should be indirectly inherited by derived classes. + + A second-order base class to test indirect inheritance + - + @@ -417,10 +521,13 @@ This function should be inherited by derived classes. + + A base class to test inheritance and shadowing + - + @@ -430,10 +537,13 @@ This function should shadow the excluded_base function. + + A base class to test inheritance and shadowing + - + @@ -443,6 +553,9 @@ This function should be shadowed by derived classes. + + A base class to test inheritance and shadowing + diff --git a/test-files/golden-tests/config/inherit-base-members/skip-special.adoc b/test-files/golden-tests/config/inherit-base-members/skip-special.adoc index a078c92ea..aad83e88a 100644 --- a/test-files/golden-tests/config/inherit-base-members/skip-special.adoc +++ b/test-files/golden-tests/config/inherit-base-members/skip-special.adoc @@ -671,6 +671,10 @@ Declared in `<skip‐special.cpp>` derived_shadowed(); ---- +=== Return Value + +Should inherit functions as protected. + [#protected_derived-do_derived_shadowed] == <>::do_derived_shadowed @@ -686,6 +690,10 @@ Declared in `<skip‐special.cpp>` do_derived_shadowed(); ---- +=== Return Value + +Should inherit functions as protected. + [#protected_derived-do_excluded_inherited] == <>::do_excluded_inherited diff --git a/test-files/golden-tests/config/inherit-base-members/skip-special.cpp b/test-files/golden-tests/config/inherit-base-members/skip-special.cpp index 3563c85fb..b8ac9b61d 100644 --- a/test-files/golden-tests/config/inherit-base-members/skip-special.cpp +++ b/test-files/golden-tests/config/inherit-base-members/skip-special.cpp @@ -1,3 +1,8 @@ +/* + A version similar to copy.cpp, with special member functions + that should not be inherited. + */ + class excluded_base { public: /// Constructor should not be inherited diff --git a/test-files/golden-tests/config/inherit-base-members/skip-special.html b/test-files/golden-tests/config/inherit-base-members/skip-special.html index 5d6c55dd9..3c55f9be1 100644 --- a/test-files/golden-tests/config/inherit-base-members/skip-special.html +++ b/test-files/golden-tests/config/inherit-base-members/skip-special.html @@ -843,6 +843,10 @@

Synopsis

+
+

Return Value

+Should inherit functions as protected. +
@@ -863,6 +867,10 @@

Synopsis

+
+

Return Value

+Should inherit functions as protected. +
diff --git a/test-files/golden-tests/config/inherit-base-members/skip-special.xml b/test-files/golden-tests/config/inherit-base-members/skip-special.xml index e4a4293da..bbb51ca5e 100644 --- a/test-files/golden-tests/config/inherit-base-members/skip-special.xml +++ b/test-files/golden-tests/config/inherit-base-members/skip-special.xml @@ -3,12 +3,12 @@ xsi:noNamespaceSchemaLocation="https://github.com/cppalliance/mrdocs/raw/develop/mrdocs.rnc"> - + - + Constructor should not be inherited @@ -16,7 +16,7 @@ - + Destructor should not be inherited @@ -24,7 +24,7 @@ - + @@ -37,7 +37,7 @@ - + @@ -50,7 +50,7 @@ - + @@ -63,7 +63,7 @@ - + @@ -76,7 +76,7 @@ - + @@ -89,7 +89,7 @@ - + @@ -102,7 +102,7 @@ - + @@ -115,7 +115,7 @@ - + @@ -129,9 +129,9 @@ - + - + Constructor should not be inherited @@ -139,7 +139,7 @@ - + Destructor should not be inherited @@ -147,7 +147,7 @@ - + @@ -160,7 +160,7 @@ - + @@ -174,7 +174,7 @@ - + @@ -182,7 +182,7 @@ - + Constructor should not be inherited @@ -190,7 +190,7 @@ - + Destructor should not be inherited @@ -198,7 +198,7 @@ - + @@ -211,7 +211,7 @@ - + @@ -224,7 +224,7 @@ - + @@ -237,7 +237,7 @@ - + @@ -250,7 +250,7 @@ - + @@ -263,7 +263,7 @@ - + @@ -276,7 +276,7 @@ - + @@ -289,7 +289,7 @@ - + @@ -302,7 +302,7 @@ - + @@ -315,7 +315,7 @@ - + @@ -328,7 +328,7 @@ - + @@ -341,7 +341,7 @@ - + @@ -355,7 +355,7 @@ - + @@ -363,7 +363,7 @@ - + Constructor should not be inherited @@ -371,7 +371,7 @@ - + Destructor should not be inherited @@ -379,7 +379,7 @@ - + @@ -392,7 +392,7 @@ - + @@ -406,7 +406,7 @@ - + @@ -419,7 +419,7 @@ - + Constructor should not be inherited @@ -427,7 +427,7 @@ - + Destructor should not be inherited @@ -435,7 +435,7 @@ - + @@ -445,10 +445,13 @@ This function should shadow the base class function. + + Should inherit functions as protected. + - + @@ -458,10 +461,13 @@ This function should shadow the base class function. + + Should inherit functions as protected. + - + @@ -474,7 +480,7 @@ - + @@ -487,7 +493,7 @@ - + @@ -500,7 +506,7 @@ - + @@ -513,7 +519,7 @@ - + @@ -526,7 +532,7 @@ - + @@ -539,7 +545,7 @@ - + @@ -552,7 +558,7 @@ - + @@ -565,7 +571,7 @@ - + @@ -578,7 +584,7 @@ - + @@ -591,7 +597,7 @@ - + diff --git a/test-files/golden-tests/config/sort/sort-members.adoc b/test-files/golden-tests/config/sort/sort-members.adoc index 996d45c93..6380cc0cf 100644 --- a/test-files/golden-tests/config/sort/sort-members.adoc +++ b/test-files/golden-tests/config/sort/sort-members.adoc @@ -33,11 +33,11 @@ | <> | | <> -| +| Negation operator | <> -| +| Equality operator | <> -| +| Inequality operator |=== [#A] @@ -165,30 +165,34 @@ struct Z; | Name | Description | <> [.small]#[constructor]# -| +| Constructors | <> [.small]#[destructor]# -| +| Destructor | <> | | <> -| +| Conversion to `bool` | <> -| +| Negation operator | <> -| +| Equality operator | <> -| +| Inequality operator | <> -| +| Three‐way comparison operator |=== [#Z-2constructor-00] == <>::Z +Constructors + === Synopses Declared in `<sort‐members.cpp>` +Default constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- @@ -197,10 +201,12 @@ Declared in `<sort‐members.cpp>` [.small]#<># +Construct from `int` + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- -<>(int); +<>(int value); ---- [.small]#<># @@ -208,6 +214,8 @@ Declared in `<sort‐members.cpp>` [#Z-2constructor-05] == <>::Z +Default constructor + === Synopsis Declared in `<sort‐members.cpp>` @@ -220,18 +228,32 @@ Z(); [#Z-2constructor-06] == <>::Z +Construct from `int` + === Synopsis Declared in `<sort‐members.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- -Z(int); +Z(int value); ---- +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *value* +| The value to construct from +|=== + [#Z-2destructor] == <>::~Z +Destructor + === Synopsis Declared in `<sort‐members.cpp>` @@ -257,6 +279,8 @@ foo() const; [#Z-2conversion] == <>::operator bool +Conversion to `bool` + === Synopsis Declared in `<sort‐members.cpp>` @@ -266,9 +290,15 @@ Declared in `<sort‐members.cpp>` operator bool() const; ---- +=== Return Value + +The object converted to `bool` + [#Z-operator_not] == <>::operator! +Negation operator + === Synopsis Declared in `<sort‐members.cpp>` @@ -279,9 +309,15 @@ bool operator!() const; ---- +=== Return Value + +`true` if the object is falsy, `false` otherwise + [#Z-operator_eq] == <>::operator== +Equality operator + === Synopsis Declared in `<sort‐members.cpp>` @@ -289,12 +325,28 @@ Declared in `<sort‐members.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- bool -operator==(<> const&) const; +operator==(<> const& rhs) const; ---- +=== Return Value + +`true` if the objects are equal, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *rhs* +| The right operand +|=== + [#Z-operator_not_eq] == <>::operator!= +Inequality operator + === Synopsis Declared in `<sort‐members.cpp>` @@ -302,12 +354,28 @@ Declared in `<sort‐members.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- bool -operator!=(<> const&) const; +operator!=(<> const& rhs) const; ---- +=== Return Value + +`true` if the objects are not equal, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *rhs* +| The right operand +|=== + [#Z-operator_3way] == <>::operator<=> +Three‐way comparison operator + === Synopsis Declared in `<sort‐members.cpp>` @@ -315,9 +383,23 @@ Declared in `<sort‐members.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- auto -operator<=>(<> const&) const; +operator<=>(<> const& rhs) const; ---- +=== Return Value + +The relative order of the objects + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *rhs* +| The right operand +|=== + [#f] == f @@ -534,6 +616,8 @@ h(); [#operator_not] == operator! +Negation operator + === Synopsis Declared in `<sort‐members.cpp>` @@ -544,9 +628,25 @@ bool operator!(<> const& v); ---- +=== Return Value + +`true` if the object is falsy, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *v* +| The operand +|=== + [#operator_eq] == operator== +Equality operator + === Synopsis Declared in `<sort‐members.cpp>` @@ -559,9 +659,27 @@ operator==( <> const& rhs); ---- +=== Return Value + +`true` if the objects are equal, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *lhs* +| The left operand +| *rhs* +| The right operand +|=== + [#operator_not_eq] == operator!= +Inequality operator + === Synopsis Declared in `<sort‐members.cpp>` @@ -574,5 +692,21 @@ operator!=( <> const& rhs); ---- +=== Return Value + +`true` if the objects are not equal, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *lhs* +| The left operand +| *rhs* +| The right operand +|=== + [.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/test-files/golden-tests/config/sort/sort-members.html b/test-files/golden-tests/config/sort/sort-members.html index 4a07a06b4..7b0c89fc5 100644 --- a/test-files/golden-tests/config/sort/sort-members.html +++ b/test-files/golden-tests/config/sort/sort-members.html @@ -43,9 +43,9 @@

Functions

f g h -operator! -operator== -operator!= +operator! Negation operator +operator== Equality operator +operator!= Inequality operator @@ -220,14 +220,14 @@

Member Functions

-Z [constructor] -~Z [destructor] +Z [constructor]Constructors +~Z [destructor]Destructor foo -operator bool -operator! -operator== -operator!= -operator<=> +operator bool Conversion to bool +operator! Negation operator +operator== Equality operator +operator!= Inequality operator +operator<=> Three-way comparison operator @@ -237,22 +237,26 @@

Member Functions

Z::Z

+
+Constructors + +

Synopses

Declared in <sort-members.cpp>
- +Default constructor 
 
 Z();
» more... - +Construct from int 
 
-Z(int);
+Z(int value);
» more... @@ -262,6 +266,10 @@

Synopses

Z::Z

+
+Default constructor + +

Synopsis

@@ -277,6 +285,10 @@

Synopsis

Z::Z

+
+Construct from int + +

Synopsis

@@ -284,14 +296,35 @@

Synopsis

Declared in <sort-members.cpp>
 
-Z(int);
+Z(int value);
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
valueThe value to construct from
+

Z::~Z

+
+Destructor + +

Synopsis

@@ -323,6 +356,10 @@

Synopsis

Z::operator bool

+
+Conversion to bool + +

Synopsis

@@ -334,10 +371,18 @@

Synopsis

+
+

Return Value

+The object converted to bool +

Z::operator!

+
+Negation operator + +

Synopsis

@@ -350,10 +395,18 @@

Synopsis

+
+

Return Value

+true if the object is falsy, false otherwise +

Z::operator==

+
+Equality operator + +

Synopsis

@@ -362,14 +415,39 @@

Synopsis

 
 bool
-operator==(Z const&) const;
+operator==(Z const& rhs) const;
+
+

Return Value

+true if the objects are equal, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
rhsThe right operand
+

Z::operator!=

+
+Inequality operator + +

Synopsis

@@ -378,14 +456,39 @@

Synopsis

 
 bool
-operator!=(Z const&) const;
+operator!=(Z const& rhs) const;
+
+

Return Value

+true if the objects are not equal, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
rhsThe right operand
+

Z::operator<=>

+
+Three-way comparison operator + +

Synopsis

@@ -394,10 +497,31 @@

Synopsis

 
 auto
-operator<=>(Z const&) const;
+operator<=>(Z const& rhs) const;
+
+

Return Value

+The relative order of the objects +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
rhsThe right operand
+
@@ -639,6 +763,10 @@

Synopsis

operator!

+
+Negation operator + +

Synopsis

@@ -651,10 +779,35 @@

Synopsis

+
+

Return Value

+true if the object is falsy, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
vThe operand
+

operator==

+
+Equality operator + +

Synopsis

@@ -669,10 +822,39 @@

Synopsis

+
+

Return Value

+true if the objects are equal, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
lhsThe left operand
rhsThe right operand
+

operator!=

+
+Inequality operator + +

Synopsis

@@ -687,6 +869,31 @@

Synopsis

+
+

Return Value

+true if the objects are not equal, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
lhsThe left operand
rhsThe right operand
+
diff --git a/test-files/golden-tests/config/sort/sort-members.xml b/test-files/golden-tests/config/sort/sort-members.xml index 2ce66d068..143cabb54 100644 --- a/test-files/golden-tests/config/sort/sort-members.xml +++ b/test-files/golden-tests/config/sort/sort-members.xml @@ -54,15 +54,34 @@ + + + Default constructor + + - + + + + Construct from + int + + + The value to construct from + + + + + Destructor + + @@ -74,6 +93,16 @@ + + + Conversion to + bool + + + The object converted to + bool + + @@ -82,6 +111,17 @@ + + + Negation operator + + + true + if the object is falsy, + false + otherwise + + @@ -90,11 +130,25 @@ - + + + + Equality operator + + + true + if the objects are equal, + false + otherwise + + + The right operand + + @@ -103,11 +157,25 @@ - + + + + Inequality operator + + + true + if the objects are not equal, + false + otherwise + + + The right operand + + @@ -117,11 +185,22 @@ - + + + + Three-way comparison operator + + + The relative order of the objects + + + The right operand + + @@ -226,6 +305,20 @@ + + + Negation operator + + + true + if the object is falsy, + false + otherwise + + + The operand + + @@ -243,6 +336,23 @@ + + + Equality operator + + + true + if the objects are equal, + false + otherwise + + + The left operand + + + The right operand + + @@ -260,6 +370,23 @@ + + + Inequality operator + + + true + if the objects are not equal, + false + otherwise + + + The left operand + + + The right operand + + diff --git a/test-files/golden-tests/config/sort/unordered.adoc b/test-files/golden-tests/config/sort/unordered.adoc index 92b0bd3e0..19af77771 100644 --- a/test-files/golden-tests/config/sort/unordered.adoc +++ b/test-files/golden-tests/config/sort/unordered.adoc @@ -27,11 +27,11 @@ | Name | Description | <> -| +| Inequality operator | <> -| +| Equality operator | <> -| +| Negation operator | <> | | <> @@ -165,26 +165,28 @@ struct Z; | Name | Description | <> -| +| Three‐way comparison operator | <> -| +| Inequality operator | <> -| +| Equality operator | <> -| +| Negation operator | <> -| +| Conversion to `bool` | <> | | <> [.small]#[destructor]# -| +| Destructor | <> [.small]#[constructor]# -| +| Constructors |=== [#Z-operator_3way] == <>::operator<=> +Three‐way comparison operator + === Synopsis Declared in `<unordered.cpp>` @@ -192,12 +194,28 @@ Declared in `<unordered.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- auto -operator<=>(<> const&) const; +operator<=>(<> const& rhs) const; ---- +=== Return Value + +The relative order of the objects + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *rhs* +| The right operand +|=== + [#Z-operator_not_eq] == <>::operator!= +Inequality operator + === Synopsis Declared in `<unordered.cpp>` @@ -205,12 +223,28 @@ Declared in `<unordered.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- bool -operator!=(<> const&) const; +operator!=(<> const& rhs) const; ---- +=== Return Value + +`true` if the objects are not equal, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *rhs* +| The right operand +|=== + [#Z-operator_eq] == <>::operator== +Equality operator + === Synopsis Declared in `<unordered.cpp>` @@ -218,12 +252,28 @@ Declared in `<unordered.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- bool -operator==(<> const&) const; +operator==(<> const& rhs) const; ---- +=== Return Value + +`true` if the objects are equal, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *rhs* +| The right operand +|=== + [#Z-operator_not] == <>::operator! +Negation operator + === Synopsis Declared in `<unordered.cpp>` @@ -234,9 +284,15 @@ bool operator!() const; ---- +=== Return Value + +`true` if the object is falsy, `false` otherwise + [#Z-2conversion] == <>::operator bool +Conversion to `bool` + === Synopsis Declared in `<unordered.cpp>` @@ -246,6 +302,10 @@ Declared in `<unordered.cpp>` operator bool() const; ---- +=== Return Value + +The object converted to `bool` + [#Z-foo] == <>::foo @@ -262,6 +322,8 @@ foo() const; [#Z-2destructor] == <>::~Z +Destructor + === Synopsis Declared in `<unordered.cpp>` @@ -274,18 +336,24 @@ Declared in `<unordered.cpp>` [#Z-2constructor-00] == <>::Z +Constructors + === Synopses Declared in `<unordered.cpp>` +Construct from `int` + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- -<>(int); +<>(int value); ---- [.small]#<># +Default constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- @@ -297,18 +365,32 @@ Declared in `<unordered.cpp>` [#Z-2constructor-06] == <>::Z +Construct from `int` + === Synopsis Declared in `<unordered.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- -Z(int); +Z(int value); ---- +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *value* +| The value to construct from +|=== + [#Z-2constructor-05] == <>::Z +Default constructor + === Synopsis Declared in `<unordered.cpp>` @@ -321,6 +403,8 @@ Z(); [#operator_not_eq] == operator!= +Inequality operator + === Synopsis Declared in `<unordered.cpp>` @@ -333,9 +417,27 @@ operator!=( <> const& rhs); ---- +=== Return Value + +`true` if the objects are not equal, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *lhs* +| The left operand +| *rhs* +| The right operand +|=== + [#operator_eq] == operator== +Equality operator + === Synopsis Declared in `<unordered.cpp>` @@ -348,9 +450,27 @@ operator==( <> const& rhs); ---- +=== Return Value + +`true` if the objects are equal, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *lhs* +| The left operand +| *rhs* +| The right operand +|=== + [#operator_not] == operator! +Negation operator + === Synopsis Declared in `<unordered.cpp>` @@ -361,6 +481,20 @@ bool operator!(<> const& v); ---- +=== Return Value + +`true` if the object is falsy, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *v* +| The operand +|=== + [#h] == h diff --git a/test-files/golden-tests/config/sort/unordered.html b/test-files/golden-tests/config/sort/unordered.html index d6635249f..eff927bd9 100644 --- a/test-files/golden-tests/config/sort/unordered.html +++ b/test-files/golden-tests/config/sort/unordered.html @@ -40,9 +40,9 @@

Functions

-operator!= -operator== -operator! +operator!= Inequality operator +operator== Equality operator +operator! Negation operator h g f @@ -220,14 +220,14 @@

Member Functions

-operator<=> -operator!= -operator== -operator! -operator bool +operator<=> Three-way comparison operator +operator!= Inequality operator +operator== Equality operator +operator! Negation operator +operator bool Conversion to bool foo -~Z [destructor] -Z [constructor] +~Z [destructor]Destructor +Z [constructor]Constructors @@ -237,6 +237,10 @@

Member Functions

Z::operator<=>

+
+Three-way comparison operator + +

Synopsis

@@ -245,14 +249,39 @@

Synopsis

 
 auto
-operator<=>(Z const&) const;
+operator<=>(Z const& rhs) const;
+
+

Return Value

+The relative order of the objects +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
rhsThe right operand
+

Z::operator!=

+
+Inequality operator + +

Synopsis

@@ -261,14 +290,39 @@

Synopsis

 
 bool
-operator!=(Z const&) const;
+operator!=(Z const& rhs) const;
+
+

Return Value

+true if the objects are not equal, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
rhsThe right operand
+

Z::operator==

+
+Equality operator + +

Synopsis

@@ -277,14 +331,39 @@

Synopsis

 
 bool
-operator==(Z const&) const;
+operator==(Z const& rhs) const;
+
+

Return Value

+true if the objects are equal, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
rhsThe right operand
+

Z::operator!

+
+Negation operator + +

Synopsis

@@ -297,10 +376,18 @@

Synopsis

+
+

Return Value

+true if the object is falsy, false otherwise +

Z::operator bool

+
+Conversion to bool + +

Synopsis

@@ -312,6 +399,10 @@

Synopsis

+
+

Return Value

+The object converted to bool +
@@ -332,6 +423,10 @@

Synopsis

Z::~Z

+
+Destructor + +

Synopsis

@@ -347,19 +442,23 @@

Synopsis

Z::Z

+
+Constructors + +

Synopses

Declared in <unordered.cpp>
- +Construct from int 
 
-Z(int);
+Z(int value);
» more... - +Default constructor 
 
 Z();
@@ -372,6 +471,10 @@ 
Synopses

 

 

 
Z::Z

+

+Construct from int
+
+

 

 

 
Synopsis

@@ -379,14 +482,35 @@ 
Synopsis

 Declared in <unordered.cpp>

 
 
-Z(int);
+Z(int value);
 
 

 

+

+
Parameters

+
+
+
+
+
+
+
+
+
+
+
+
+
+
NameDescription
valueThe value to construct from

+

Z::Z

+
+Default constructor + +

Synopsis

@@ -402,6 +526,10 @@

Synopsis

operator!=

+
+Inequality operator + +

Synopsis

@@ -416,10 +544,39 @@

Synopsis
+
+

Return Value

+true if the objects are not equal, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
lhsThe left operand
rhsThe right operand
+

operator==

+
+Equality operator + +

Synopsis

@@ -434,10 +591,39 @@

Synopsis

+
+

Return Value

+true if the objects are equal, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
lhsThe left operand
rhsThe right operand
+

operator!

+
+Negation operator + +

Synopsis

@@ -450,6 +636,27 @@

Synopsis

+
+

Return Value

+true if the object is falsy, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
vThe operand
+
diff --git a/test-files/golden-tests/config/sort/unordered.xml b/test-files/golden-tests/config/sort/unordered.xml index 9326d67b1..0657884e7 100644 --- a/test-files/golden-tests/config/sort/unordered.xml +++ b/test-files/golden-tests/config/sort/unordered.xml @@ -60,11 +60,22 @@ - + + + + Three-way comparison operator + + + The relative order of the objects + + + The right operand + + @@ -73,11 +84,25 @@ - + + + + Inequality operator + + + true + if the objects are not equal, + false + otherwise + + + The right operand + + @@ -86,11 +111,25 @@ - + + + + Equality operator + + + true + if the objects are equal, + false + otherwise + + + The right operand + + @@ -99,6 +138,17 @@ + + + Negation operator + + + true + if the object is falsy, + false + otherwise + + @@ -106,6 +156,16 @@ + + + Conversion to + bool + + + The object converted to + bool + + @@ -113,15 +173,34 @@ + + + Destructor + + - + + + + Construct from + int + + + The value to construct from + + + + + Default constructor + + @@ -140,6 +219,23 @@ + + + Inequality operator + + + true + if the objects are not equal, + false + otherwise + + + The left operand + + + The right operand + + @@ -157,6 +253,23 @@ + + + Equality operator + + + true + if the objects are equal, + false + otherwise + + + The left operand + + + The right operand + + @@ -169,6 +282,20 @@ + + + Negation operator + + + true + if the object is falsy, + false + otherwise + + + The operand + + diff --git a/test-files/golden-tests/filters/symbol-name/extraction-mode.adoc b/test-files/golden-tests/filters/symbol-name/extraction-mode.adoc index 55a4fe506..0dab626ee 100644 --- a/test-files/golden-tests/filters/symbol-name/extraction-mode.adoc +++ b/test-files/golden-tests/filters/symbol-name/extraction-mode.adoc @@ -225,6 +225,10 @@ When used in a function, the implementation‐defined comment should replac It's the responsibility of the function documentation to explain the implementation‐defined symbol. +=== Return Value + +A symbol that passes the implementation‐defined filter + [#regular_ns-get_regular] == <>::get_regular @@ -244,6 +248,10 @@ get_regular(); When used in a function, the symbol should be shown as usual with a link to the page. +=== Return Value + +A symbol that passes the filters + [#regular_ns-get_see_below] == <>::get_see_below @@ -263,6 +271,10 @@ get_see_below(); When used in a function, the symbol name should be shown as usual. The page for this symbol is what should be different because the synopsis should say "See below" and the members are not listed unless it's a namespace or the symbol has been explicitly used as a dependency elsewhere. +=== Return Value + +A symbol that passes the see‐below filter + [#see_below_ns] == see_below_ns @@ -376,6 +388,10 @@ When used in a function, the implementation‐defined comment should replac It's the responsibility of the function documentation to explain the implementation‐defined symbol. +=== Return Value + +Implementation‐defined symbol in a see‐below namespace + [#dependency_ns_alias] == dependency_ns_alias @@ -558,6 +574,10 @@ When used in a function, the implementation‐defined comment should replac It's the responsibility of the function documentation to explain the implementation‐defined symbol. +=== Return Value + +An implementation‐defined symbol in the global namespace + [#get_regular] == get_regular @@ -577,6 +597,10 @@ get_regular(); When used in a function, the symbol should be shown as usual with a link to the page. +=== Return Value + +A regular symbol in the global namespace + [#get_see_below] == get_see_below @@ -596,5 +620,9 @@ get_see_below(); When used in a function, the symbol name should be shown as usual. The page for this symbol is what should be different because the synopsis should say "See below" and the members are not listed unless it's a namespace or the symbol has been explicitly used as a dependency elsewhere. +=== Return Value + +A see‐below symbol in the global namespace + [.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/test-files/golden-tests/filters/symbol-name/extraction-mode.html b/test-files/golden-tests/filters/symbol-name/extraction-mode.html index 65531b895..706b1ecca 100644 --- a/test-files/golden-tests/filters/symbol-name/extraction-mode.html +++ b/test-files/golden-tests/filters/symbol-name/extraction-mode.html @@ -296,6 +296,10 @@

Description

When used in a function, the implementation-defined comment should replace the real type.

It's the responsibility of the function documentation to explain the implementation-defined symbol.

+
+

Return Value

+A symbol that passes the implementation-defined filter +
@@ -320,6 +324,10 @@

Synopsis

Description

When used in a function, the symbol should be shown as usual with a link to the page.

+
+

Return Value

+A symbol that passes the filters +
@@ -344,6 +352,10 @@

Synopsis

Description

When used in a function, the symbol name should be shown as usual. The page for this symbol is what should be different because the synopsis should say "See below" and the members are not listed unless it's a namespace or the symbol has been explicitly used as a dependency elsewhere.

+
+

Return Value

+A symbol that passes the see-below filter +
@@ -488,6 +500,10 @@

Description

When used in a function, the implementation-defined comment should replace the real type.

It's the responsibility of the function documentation to explain the implementation-defined symbol.

+
+

Return Value

+Implementation-defined symbol in a see-below namespace +
@@ -733,6 +749,10 @@

Description

When used in a function, the implementation-defined comment should replace the real type.

It's the responsibility of the function documentation to explain the implementation-defined symbol.

+
+

Return Value

+An implementation-defined symbol in the global namespace +
@@ -757,6 +777,10 @@

Synopsis

Description

When used in a function, the symbol should be shown as usual with a link to the page.

+
+

Return Value

+A regular symbol in the global namespace +
@@ -781,6 +805,10 @@

Synopsis

Description

When used in a function, the symbol name should be shown as usual. The page for this symbol is what should be different because the synopsis should say "See below" and the members are not listed unless it's a namespace or the symbol has been explicitly used as a dependency elsewhere.

+
+

Return Value

+A see-below symbol in the global namespace +
diff --git a/test-files/golden-tests/filters/symbol-name/extraction-mode.xml b/test-files/golden-tests/filters/symbol-name/extraction-mode.xml index 0780a1d15..e2f4695d9 100644 --- a/test-files/golden-tests/filters/symbol-name/extraction-mode.xml +++ b/test-files/golden-tests/filters/symbol-name/extraction-mode.xml @@ -99,6 +99,9 @@ It's the responsibility of the function documentation to explain the implementation-defined symbol. + + A symbol that passes the implementation-defined filter + @@ -113,6 +116,9 @@ When used in a function, the symbol should be shown as usual with a link to the page. + + A symbol that passes the filters + regular @@ -130,6 +136,9 @@ When used in a function, the symbol name should be shown as usual. The page for this symbol is what should be different because the synopsis should say "See below" and the members are not listed unless it's a namespace or the symbol has been explicitly used as a dependency elsewhere. + + A symbol that passes the see-below filter + @@ -213,6 +222,9 @@ It's the responsibility of the function documentation to explain the implementation-defined symbol. + + Implementation-defined symbol in a see-below namespace + @@ -330,6 +342,9 @@ It's the responsibility of the function documentation to explain the implementation-defined symbol. + + An implementation-defined symbol in the global namespace + @@ -344,6 +359,9 @@ When used in a function, the symbol should be shown as usual with a link to the page. + + A regular symbol in the global namespace + regular @@ -361,6 +379,9 @@ When used in a function, the symbol name should be shown as usual. The page for this symbol is what should be different because the synopsis should say "See below" and the members are not listed unless it's a namespace or the symbol has been explicitly used as a dependency elsewhere. + + A see-below symbol in the global namespace + diff --git a/test-files/golden-tests/filters/symbol-name/whitelist_0.xml b/test-files/golden-tests/filters/symbol-name/whitelist_0.xml index 9c4c2d8c0..1150be74d 100644 --- a/test-files/golden-tests/filters/symbol-name/whitelist_0.xml +++ b/test-files/golden-tests/filters/symbol-name/whitelist_0.xml @@ -41,7 +41,8 @@ This function should extracted because the namespace N1::N3_WL - is included as a literal. + is included + as a literal. @@ -91,7 +92,8 @@ This function should be included because it's a member of M7 - , which matches + , which matches + N5::N6::*7 @@ -110,7 +112,8 @@ This function should be included because it's a member of N7 - , which matches + , which matches + N5::N6::*7 diff --git a/test-files/golden-tests/javadoc/ref/ref.adoc b/test-files/golden-tests/javadoc/ref/ref.adoc index 01e5298f7..e65965cae 100644 --- a/test-files/golden-tests/javadoc/ref/ref.adoc +++ b/test-files/golden-tests/javadoc/ref/ref.adoc @@ -322,7 +322,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator=(<>&); +operator=(<>& other); ---- [#F-operator_mod] @@ -335,7 +335,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator%(<>&); +operator%(<>& rhs); ---- [#F-operator_mod_eq] @@ -348,7 +348,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator%=(<>&); +operator%=(<>& rhs); ---- [#F-operator_bitand] @@ -361,7 +361,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator&(<>&); +operator&(<>& rhs); ---- [#F-operator_and] @@ -374,7 +374,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator&&(<>&); +operator&&(<>& rhs); ---- [#F-operator_and_eq] @@ -387,7 +387,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator&=(<>&); +operator&=(<>& rhs); ---- [#F-operator_call] @@ -400,7 +400,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator()(<>&); +operator()(<>& rhs); ---- [#F-operator_star] @@ -413,7 +413,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator*(<>&); +operator*(<>& rhs); ---- [#F-operator_star_eq] @@ -426,7 +426,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator*=(<>&); +operator*=(<>& rhs); ---- [#F-operator_plus] @@ -439,7 +439,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator+(<>&); +operator+(<>& rhs); ---- [#F-operator_inc] @@ -465,7 +465,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator+=(<>&); +operator+=(<>& rhs); ---- [#F-operator_comma] @@ -478,7 +478,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator,(<>&); +operator,(<>& rhs); ---- [#F-operator_minus] @@ -491,7 +491,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator‐(<>&); +operator‐(<>& rhs); ---- [#F-operator_dec] @@ -517,7 +517,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator‐=(<>&); +operator‐=(<>& rhs); ---- [#F-operator_ptr] @@ -543,7 +543,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator‐>*(<>&); +operator‐>*(<>& rhs); ---- [#F-operator_slash] @@ -556,7 +556,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator/(<>&); +operator/(<>& rhs); ---- [#F-operator_slash_eq] @@ -569,7 +569,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator/=(<>&); +operator/=(<>& rhs); ---- [#F-operator_lshift_eq] @@ -582,7 +582,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator<<=(<>&); +operator<<=(<>& rhs); ---- [#F-operator_rshift] @@ -595,7 +595,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator>>(<>&); +operator>>(<>& rhs); ---- [#F-operator_rshift_eq] @@ -608,7 +608,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator>>=(<>&); +operator>>=(<>& rhs); ---- [#F-operator_subs] @@ -621,7 +621,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator[](<>&); +operator[](<>& rhs); ---- [#F-operator_xor] @@ -634,7 +634,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operatorˆ(<>&); +operatorˆ(<>& rhs); ---- [#F-operator_xor_eq] @@ -647,7 +647,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operatorˆ=(<>&); +operatorˆ=(<>& rhs); ---- [#F-operator_bitor] @@ -660,7 +660,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator|(<>&); +operator|(<>& rhs); ---- [#F-operator_or_eq] @@ -673,7 +673,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator|=(<>&); +operator|=(<>& rhs); ---- [#F-operator_or] @@ -686,7 +686,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator||(<>&); +operator||(<>& rhs); ---- [#F-operator_bitnot] @@ -712,7 +712,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator<<(<>&); +operator<<(<>& rhs); ---- [#F-operator_not] @@ -738,7 +738,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator==(<>&); +operator==(<>& rhs); ---- [#F-operator_not_eq] @@ -751,7 +751,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator!=(<>&); +operator!=(<>& rhs); ---- [#F-operator_lt] @@ -764,7 +764,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator<(<>&); +operator<(<>& rhs); ---- [#F-operator_le] @@ -777,7 +777,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator<=(<>&); +operator<=(<>& rhs); ---- [#F-operator_gt] @@ -790,7 +790,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator>(<>&); +operator>(<>& rhs); ---- [#F-operator_ge] @@ -803,7 +803,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator>=(<>&); +operator>=(<>& rhs); ---- [#F-operator_3way] @@ -816,7 +816,7 @@ Declared in `<ref.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- void -operator<=>(<>&); +operator<=>(<>& rhs); ---- [#f0] diff --git a/test-files/golden-tests/javadoc/ref/ref.html b/test-files/golden-tests/javadoc/ref/ref.html index a77d6f0ae..6947c373b 100644 --- a/test-files/golden-tests/javadoc/ref/ref.html +++ b/test-files/golden-tests/javadoc/ref/ref.html @@ -426,7 +426,7 @@

Synopsis

 
 void
-operator=(F&);
+operator=(F& other);
@@ -442,7 +442,7 @@

Synopsis

 
 void
-operator%(F&);
+operator%(F& rhs);
@@ -458,7 +458,7 @@

Synopsis

 
 void
-operator%=(F&);
+operator%=(F& rhs);
@@ -474,7 +474,7 @@

Synopsis

 
 void
-operator&(F&);
+operator&(F& rhs);
@@ -490,7 +490,7 @@

Synopsis

 
 void
-operator&&(F&);
+operator&&(F& rhs);
@@ -506,7 +506,7 @@

Synopsis

 
 void
-operator&=(F&);
+operator&=(F& rhs);
@@ -522,7 +522,7 @@

Synopsis

 
 void
-operator()(F&);
+operator()(F& rhs);
@@ -538,7 +538,7 @@

Synopsis

 
 void
-operator*(F&);
+operator*(F& rhs);
@@ -554,7 +554,7 @@

Synopsis

 
 void
-operator*=(F&);
+operator*=(F& rhs);
@@ -570,7 +570,7 @@

Synopsis

 
 void
-operator+(F&);
+operator+(F& rhs);
@@ -602,7 +602,7 @@

Synopsis

 
 void
-operator+=(F&);
+operator+=(F& rhs);
@@ -618,7 +618,7 @@

Synopsis

 
 void
-operator,(F&);
+operator,(F& rhs);
@@ -634,7 +634,7 @@

Synopsis

 
 void
-operator-(F&);
+operator-(F& rhs);
@@ -666,7 +666,7 @@

Synopsis

 
 void
-operator-=(F&);
+operator-=(F& rhs);
@@ -698,7 +698,7 @@

Synopsis

 
 void
-operator->*(F&);
+operator->*(F& rhs);
@@ -714,7 +714,7 @@

Synopsis

 
 void
-operator/(F&);
+operator/(F& rhs);
@@ -730,7 +730,7 @@

Synopsis

 
 void
-operator/=(F&);
+operator/=(F& rhs);
@@ -746,7 +746,7 @@

Synopsis

 
 void
-operator<<=(F&);
+operator<<=(F& rhs);
@@ -762,7 +762,7 @@

Synopsis

 
 void
-operator>>(F&);
+operator>>(F& rhs);
@@ -778,7 +778,7 @@

Synopsis

 
 void
-operator>>=(F&);
+operator>>=(F& rhs);
@@ -794,7 +794,7 @@

Synopsis

 
 void
-operator[](F&);
+operator[](F& rhs);
@@ -810,7 +810,7 @@

Synopsis

 
 void
-operator^(F&);
+operator^(F& rhs);
@@ -826,7 +826,7 @@

Synopsis

 
 void
-operator^=(F&);
+operator^=(F& rhs);
@@ -842,7 +842,7 @@

Synopsis

 
 void
-operator|(F&);
+operator|(F& rhs);
@@ -858,7 +858,7 @@

Synopsis

 
 void
-operator|=(F&);
+operator|=(F& rhs);
@@ -874,7 +874,7 @@

Synopsis

 
 void
-operator||(F&);
+operator||(F& rhs);
@@ -906,7 +906,7 @@

Synopsis

 
 void
-operator<<(F&);
+operator<<(F& rhs);
@@ -938,7 +938,7 @@

Synopsis

 
 void
-operator==(F&);
+operator==(F& rhs);
@@ -954,7 +954,7 @@

Synopsis

 
 void
-operator!=(F&);
+operator!=(F& rhs);
@@ -970,7 +970,7 @@

Synopsis

 
 void
-operator<(F&);
+operator<(F& rhs);
@@ -986,7 +986,7 @@

Synopsis

 
 void
-operator<=(F&);
+operator<=(F& rhs);
@@ -1002,7 +1002,7 @@

Synopsis

 
 void
-operator>(F&);
+operator>(F& rhs);
@@ -1018,7 +1018,7 @@

Synopsis

 
 void
-operator>=(F&);
+operator>=(F& rhs);
@@ -1034,7 +1034,7 @@

Synopsis

 
 void
-operator<=>(F&);
+operator<=>(F& rhs);
diff --git a/test-files/golden-tests/javadoc/ref/ref.xml b/test-files/golden-tests/javadoc/ref/ref.xml index 36e03d334..7f4ddcaca 100644 --- a/test-files/golden-tests/javadoc/ref/ref.xml +++ b/test-files/golden-tests/javadoc/ref/ref.xml @@ -83,7 +83,7 @@ - + @@ -92,7 +92,7 @@ - + @@ -101,7 +101,7 @@ - + @@ -110,7 +110,7 @@ - + @@ -119,7 +119,7 @@ - + @@ -128,7 +128,7 @@ - + @@ -137,7 +137,7 @@ - + @@ -146,7 +146,7 @@ - + @@ -155,7 +155,7 @@ - + @@ -164,7 +164,7 @@ - + @@ -177,7 +177,7 @@ - + @@ -186,7 +186,7 @@ - + @@ -195,7 +195,7 @@ - + @@ -208,7 +208,7 @@ - + @@ -221,7 +221,7 @@ - + @@ -230,7 +230,7 @@ - + @@ -239,7 +239,7 @@ - + @@ -248,7 +248,7 @@ - + @@ -257,7 +257,7 @@ - + @@ -266,7 +266,7 @@ - + @@ -275,7 +275,7 @@ - + @@ -284,7 +284,7 @@ - + @@ -293,7 +293,7 @@ - + @@ -302,7 +302,7 @@ - + @@ -311,7 +311,7 @@ - + @@ -320,7 +320,7 @@ - + @@ -333,7 +333,7 @@ - + @@ -346,7 +346,7 @@ - + @@ -355,7 +355,7 @@ - + @@ -364,7 +364,7 @@ - + @@ -373,7 +373,7 @@ - + @@ -382,7 +382,7 @@ - + @@ -391,7 +391,7 @@ - + @@ -400,7 +400,7 @@ - + diff --git a/test-files/golden-tests/symbols/function/explicit-conv-operator.adoc b/test-files/golden-tests/symbols/function/explicit-conv-operator.adoc index 945314209..b90545fb4 100644 --- a/test-files/golden-tests/symbols/function/explicit-conv-operator.adoc +++ b/test-files/golden-tests/symbols/function/explicit-conv-operator.adoc @@ -29,15 +29,19 @@ struct Explicit; === Member Functions -[cols=1] +[cols=2] |=== | Name +| Description | <> +| Conversion to `bool` |=== [#Explicit-2conversion] == <>::operator bool +Conversion to `bool` + === Synopsis Declared in `<explicit‐conv‐operator.cpp>` @@ -48,6 +52,10 @@ explicit operator bool(); ---- +=== Return Value + +The object converted to `bool` + [#ExplicitExpression] == ExplicitExpression @@ -63,15 +71,19 @@ struct ExplicitExpression; === Member Functions -[cols=1] +[cols=2] |=== | Name +| Description | <> +| Conversion to `bool` |=== [#ExplicitExpression-2conversion] == <>::operator bool +Conversion to `bool` + === Synopsis Declared in `<explicit‐conv‐operator.cpp>` @@ -82,6 +94,10 @@ explicit(B) operator bool(); ---- +=== Return Value + +The object converted to `bool` + [#ExplicitFalse] == ExplicitFalse @@ -96,15 +112,19 @@ struct ExplicitFalse; === Member Functions -[cols=1] +[cols=2] |=== | Name +| Description | <> +| Conversion to `bool` |=== [#ExplicitFalse-2conversion] == <>::operator bool +Conversion to `bool` + === Synopsis Declared in `<explicit‐conv‐operator.cpp>` @@ -115,6 +135,10 @@ explicit(false) operator bool(); ---- +=== Return Value + +The object converted to `bool` + [#ExplicitTrue] == ExplicitTrue @@ -129,15 +153,19 @@ struct ExplicitTrue; === Member Functions -[cols=1] +[cols=2] |=== | Name +| Description | <> +| Conversion to `bool` |=== [#ExplicitTrue-2conversion] == <>::operator bool +Conversion to `bool` + === Synopsis Declared in `<explicit‐conv‐operator.cpp>` @@ -148,5 +176,9 @@ explicit(true) operator bool(); ---- +=== Return Value + +The object converted to `bool` + [.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/test-files/golden-tests/symbols/function/explicit-conv-operator.html b/test-files/golden-tests/symbols/function/explicit-conv-operator.html index 8681026f5..c719ab515 100644 --- a/test-files/golden-tests/symbols/function/explicit-conv-operator.html +++ b/test-files/golden-tests/symbols/function/explicit-conv-operator.html @@ -45,11 +45,12 @@

Member Functions

Name +Description -operator bool +operator bool Conversion to bool @@ -59,6 +60,10 @@

Member Functions

Explicit::operator bool

+
+Conversion to bool + +

Synopsis

@@ -71,6 +76,10 @@

Synopsis

+
+

Return Value

+The object converted to bool +
@@ -92,11 +101,12 @@

Member Functions

Name +Description -operator bool +operator bool Conversion to bool @@ -106,6 +116,10 @@

Member Functions

ExplicitExpression::operator bool

+
+Conversion to bool + +

Synopsis

@@ -118,6 +132,10 @@

Synopsis

+
+

Return Value

+The object converted to bool +
@@ -138,11 +156,12 @@

Member Functions

Name +Description -operator bool +operator bool Conversion to bool @@ -152,6 +171,10 @@

Member Functions

ExplicitFalse::operator bool

+
+Conversion to bool + +

Synopsis

@@ -164,6 +187,10 @@

Synopsis

+
+

Return Value

+The object converted to bool +
@@ -184,11 +211,12 @@

Member Functions

Name +Description -operator bool +operator bool Conversion to bool @@ -198,6 +226,10 @@

Member Functions

ExplicitTrue::operator bool

+
+Conversion to bool + +

Synopsis

@@ -210,6 +242,10 @@

Synopsis

+
+

Return Value

+The object converted to bool +
diff --git a/test-files/golden-tests/symbols/function/explicit-conv-operator.xml b/test-files/golden-tests/symbols/function/explicit-conv-operator.xml index 0c30f1dfe..c4b72a0be 100644 --- a/test-files/golden-tests/symbols/function/explicit-conv-operator.xml +++ b/test-files/golden-tests/symbols/function/explicit-conv-operator.xml @@ -9,6 +9,16 @@ + + + Conversion to + bool + + + The object converted to + bool + + @@ -30,6 +50,16 @@ + + + Conversion to + bool + + + The object converted to + bool + + @@ -39,6 +69,16 @@ + + + Conversion to + bool + + + The object converted to + bool + + diff --git a/test-files/golden-tests/symbols/function/explicit-ctor.adoc b/test-files/golden-tests/symbols/function/explicit-ctor.adoc index 1a9cbb885..9e7a5bbd9 100644 --- a/test-files/golden-tests/symbols/function/explicit-ctor.adoc +++ b/test-files/golden-tests/symbols/function/explicit-ctor.adoc @@ -34,16 +34,20 @@ struct Explicit; | Name | Description | <> [.small]#[constructor]# -| +| Constructors |=== [#Explicit-2constructor-08] == <>::Explicit +Constructors + === Synopses Declared in `<explicit‐ctor.cpp>` +Default constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- @@ -53,24 +57,30 @@ explicit [.small]#<># +Copy constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- explicit -<>(<> const&); +<>(<> const& other); ---- [.small]#<># +Move constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- explicit -<>(<>&&) noexcept; +<>(<>&& other) noexcept; ---- [.small]#<># +Constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- @@ -85,6 +95,8 @@ explicit [#Explicit-2constructor-02] == <>::Explicit +Default constructor + === Synopsis Declared in `<explicit‐ctor.cpp>` @@ -98,6 +110,8 @@ Explicit(); [#Explicit-2constructor-00] == <>::Explicit +Copy constructor + === Synopsis Declared in `<explicit‐ctor.cpp>` @@ -105,12 +119,24 @@ Declared in `<explicit‐ctor.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- explicit -Explicit(<> const&); +Explicit(<> const& other); ---- +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *other* +| The object to copy construct from +|=== + [#Explicit-2constructor-0b] == <>::Explicit +Move constructor + === Synopsis Declared in `<explicit‐ctor.cpp>` @@ -118,12 +144,24 @@ Declared in `<explicit‐ctor.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- explicit -Explicit(<>&&) noexcept; +Explicit(<>&& other) noexcept; ---- +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *other* +| The object to move construct from +|=== + [#Explicit-2constructor-03] == <>::Explicit +Constructor + === Synopsis Declared in `<explicit‐ctor.cpp>` @@ -156,16 +194,20 @@ struct ExplicitExpression; | Name | Description | <> [.small]#[constructor]# -| +| Constructors |=== [#ExplicitExpression-2constructor-026] == <>::ExplicitExpression +Constructors + === Synopses Declared in `<explicit‐ctor.cpp>` +Default constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- @@ -175,24 +217,30 @@ explicit(B) [.small]#<># +Copy constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- explicit(B) -<>(<> const&); +<>(<> const& other); ---- [.small]#<># +Move constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- explicit(B) -<>(<>&&) noexcept; +<>(<>&& other) noexcept; ---- [.small]#<># +Constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- @@ -207,6 +255,8 @@ explicit(B) [#ExplicitExpression-2constructor-0b] == <>::ExplicitExpression +Default constructor + === Synopsis Declared in `<explicit‐ctor.cpp>` @@ -220,6 +270,8 @@ ExplicitExpression(); [#ExplicitExpression-2constructor-04] == <>::ExplicitExpression +Copy constructor + === Synopsis Declared in `<explicit‐ctor.cpp>` @@ -227,12 +279,24 @@ Declared in `<explicit‐ctor.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- explicit(B) -ExplicitExpression(<> const&); +ExplicitExpression(<> const& other); ---- +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *other* +| The object to copy construct from +|=== + [#ExplicitExpression-2constructor-08] == <>::ExplicitExpression +Move constructor + === Synopsis Declared in `<explicit‐ctor.cpp>` @@ -240,12 +304,24 @@ Declared in `<explicit‐ctor.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- explicit(B) -ExplicitExpression(<>&&) noexcept; +ExplicitExpression(<>&& other) noexcept; ---- +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *other* +| The object to move construct from +|=== + [#ExplicitExpression-2constructor-027] == <>::ExplicitExpression +Constructor + === Synopsis Declared in `<explicit‐ctor.cpp>` @@ -277,16 +353,20 @@ struct ExplicitFalse; | Name | Description | <> [.small]#[constructor]# -| +| Constructors |=== [#ExplicitFalse-2constructor-04c] == <>::ExplicitFalse +Constructors + === Synopses Declared in `<explicit‐ctor.cpp>` +Default constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- @@ -296,24 +376,30 @@ explicit(false) [.small]#<># +Copy constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- explicit(false) -<>(<> const&); +<>(<> const& other); ---- [.small]#<># +Move constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- explicit(false) -<>(<>&&) noexcept; +<>(<>&& other) noexcept; ---- [.small]#<># +Constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- @@ -328,6 +414,8 @@ explicit(false) [#ExplicitFalse-2constructor-01] == <>::ExplicitFalse +Default constructor + === Synopsis Declared in `<explicit‐ctor.cpp>` @@ -341,6 +429,8 @@ ExplicitFalse(); [#ExplicitFalse-2constructor-08] == <>::ExplicitFalse +Copy constructor + === Synopsis Declared in `<explicit‐ctor.cpp>` @@ -348,12 +438,24 @@ Declared in `<explicit‐ctor.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- explicit(false) -ExplicitFalse(<> const&); +ExplicitFalse(<> const& other); ---- +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *other* +| The object to copy construct from +|=== + [#ExplicitFalse-2constructor-0a] == <>::ExplicitFalse +Move constructor + === Synopsis Declared in `<explicit‐ctor.cpp>` @@ -361,12 +463,24 @@ Declared in `<explicit‐ctor.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- explicit(false) -ExplicitFalse(<>&&) noexcept; +ExplicitFalse(<>&& other) noexcept; ---- +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *other* +| The object to move construct from +|=== + [#ExplicitFalse-2constructor-04f] == <>::ExplicitFalse +Constructor + === Synopsis Declared in `<explicit‐ctor.cpp>` @@ -398,16 +512,20 @@ struct ExplicitTrue; | Name | Description | <> [.small]#[constructor]# -| +| Constructors |=== [#ExplicitTrue-2constructor-0f] == <>::ExplicitTrue +Constructors + === Synopses Declared in `<explicit‐ctor.cpp>` +Default constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- @@ -417,24 +535,30 @@ explicit(true) [.small]#<># +Copy constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- explicit(true) -<>(<> const&); +<>(<> const& other); ---- [.small]#<># +Move constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- explicit(true) -<>(<>&&) noexcept; +<>(<>&& other) noexcept; ---- [.small]#<># +Constructor + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- @@ -449,6 +573,8 @@ explicit(true) [#ExplicitTrue-2constructor-0d] == <>::ExplicitTrue +Default constructor + === Synopsis Declared in `<explicit‐ctor.cpp>` @@ -462,6 +588,8 @@ ExplicitTrue(); [#ExplicitTrue-2constructor-04] == <>::ExplicitTrue +Copy constructor + === Synopsis Declared in `<explicit‐ctor.cpp>` @@ -469,12 +597,24 @@ Declared in `<explicit‐ctor.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- explicit(true) -ExplicitTrue(<> const&); +ExplicitTrue(<> const& other); ---- +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *other* +| The object to copy construct from +|=== + [#ExplicitTrue-2constructor-08] == <>::ExplicitTrue +Move constructor + === Synopsis Declared in `<explicit‐ctor.cpp>` @@ -482,12 +622,24 @@ Declared in `<explicit‐ctor.cpp>` [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- explicit(true) -ExplicitTrue(<>&&) noexcept; +ExplicitTrue(<>&& other) noexcept; ---- +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *other* +| The object to move construct from +|=== + [#ExplicitTrue-2constructor-05] == <>::ExplicitTrue +Constructor + === Synopsis Declared in `<explicit‐ctor.cpp>` diff --git a/test-files/golden-tests/symbols/function/explicit-ctor.html b/test-files/golden-tests/symbols/function/explicit-ctor.html index ccd110aea..ff2e4841f 100644 --- a/test-files/golden-tests/symbols/function/explicit-ctor.html +++ b/test-files/golden-tests/symbols/function/explicit-ctor.html @@ -50,7 +50,7 @@

Member Functions

-Explicit [constructor] +Explicit [constructor]Constructors @@ -60,12 +60,16 @@

Member Functions

Explicit::Explicit

+
+Constructors + +

Synopses

Declared in <explicit-ctor.cpp>
- +Default constructor 
 
 explicit
@@ -73,23 +77,23 @@ 
Synopses
» more... - +Copy constructor 
 
 explicit
-Explicit(Explicit const&);
+Explicit(Explicit const& other);
» more... - +Move constructor 
 
 explicit
-Explicit(Explicit&&) noexcept;
+Explicit(Explicit&& other) noexcept;
» more... - +Constructor 
 
 explicit
@@ -105,6 +109,10 @@ 
Synopses

 

 

 
Explicit::Explicit

+

+Default constructor
+
+

 

 

 
Synopsis

@@ -121,6 +129,10 @@ 
Synopsis

 

 

 
Explicit::Explicit

+

+Copy constructor
+
+

 

 

 
Synopsis

@@ -129,14 +141,35 @@ 
Synopsis

 
 
 explicit
-Explicit(Explicit const&);
+Explicit(Explicit const& other);
 
 

 

+

+
Parameters

+
+
+
+
+
+
+
+
+
+
+
+
+
+
NameDescription
otherThe object to copy construct from

+

 

 

 

 
Explicit::Explicit

+

+Move constructor
+
+

 

 

 
Synopsis

@@ -145,14 +178,35 @@ 
Synopsis

 
 
 explicit
-Explicit(Explicit&&) noexcept;
+Explicit(Explicit&& other) noexcept;
 
 

 

+

+
Parameters

+
+
+
+
+
+
+
+
+
+
+
+
+
+
NameDescription
otherThe object to move construct from

+

 

 

 

 
Explicit::Explicit

+

+Constructor
+
+

 

 

 
Synopsis

@@ -193,7 +247,7 @@ 
Member Functions

 
 
 
-ExplicitExpression         [constructor]
+ExplicitExpression         [constructor]Constructors
 
 
 
@@ -203,12 +257,16 @@ 
Member Functions

 

 

 
ExplicitExpression::ExplicitExpression

+

+Constructors
+
+

 

 

 
Synopses

 

 Declared in <explicit-ctor.cpp>

-
+Default constructor
 
 
 explicit(B)
@@ -216,23 +274,23 @@ 
Synopses

 
 
» more...
 
-
+Copy constructor
 
 
 explicit(B)
-ExplicitExpression(ExplicitExpression const&);
+ExplicitExpression(ExplicitExpression const& other);
 
 
» more...
 
-
+Move constructor
 
 
 explicit(B)
-ExplicitExpression(ExplicitExpression&&) noexcept;
+ExplicitExpression(ExplicitExpression&& other) noexcept;
 
 
» more...
 
-
+Constructor
 
 
 explicit(B)
@@ -248,6 +306,10 @@ 
Synopses

 

 

 
ExplicitExpression::ExplicitExpression

+

+Default constructor
+
+

 

 

 
Synopsis

@@ -264,6 +326,10 @@ 
Synopsis

 

 

 
ExplicitExpression::ExplicitExpression

+

+Copy constructor
+
+

 

 

 
Synopsis

@@ -272,14 +338,35 @@ 
Synopsis

 
 
 explicit(B)
-ExplicitExpression(ExplicitExpression const&);
+ExplicitExpression(ExplicitExpression const& other);
 
 

 

+

+
Parameters

+
+
+
+
+
+
+
+
+
+
+
+
+
+
NameDescription
otherThe object to copy construct from

+

 

 

 

 
ExplicitExpression::ExplicitExpression

+

+Move constructor
+
+

 

 

 
Synopsis

@@ -288,14 +375,35 @@ 
Synopsis

 
 
 explicit(B)
-ExplicitExpression(ExplicitExpression&&) noexcept;
+ExplicitExpression(ExplicitExpression&& other) noexcept;
 
 

 

+

+
Parameters

+
+
+
+
+
+
+
+
+
+
+
+
+
+
NameDescription
otherThe object to move construct from

+

 

 

 

 
ExplicitExpression::ExplicitExpression

+

+Constructor
+
+

 

 

 
Synopsis

@@ -335,7 +443,7 @@ 
Member Functions

 
 
 
-ExplicitFalse         [constructor]
+ExplicitFalse         [constructor]Constructors
 
 
 
@@ -345,12 +453,16 @@ 
Member Functions

 

 

 
ExplicitFalse::ExplicitFalse

+

+Constructors
+
+

 

 

 
Synopses

 

 Declared in <explicit-ctor.cpp>

-
+Default constructor
 
 
 explicit(false)
@@ -358,23 +470,23 @@ 
Synopses

 
 
» more...
 
-
+Copy constructor
 
 
 explicit(false)
-ExplicitFalse(ExplicitFalse const&);
+ExplicitFalse(ExplicitFalse const& other);
 
 
» more...
 
-
+Move constructor
 
 
 explicit(false)
-ExplicitFalse(ExplicitFalse&&) noexcept;
+ExplicitFalse(ExplicitFalse&& other) noexcept;
 
 
» more...
 
-
+Constructor
 
 
 explicit(false)
@@ -390,6 +502,10 @@ 
Synopses

 

 

 
ExplicitFalse::ExplicitFalse

+

+Default constructor
+
+

 

 

 
Synopsis

@@ -406,6 +522,10 @@ 
Synopsis

 

 

 
ExplicitFalse::ExplicitFalse

+

+Copy constructor
+
+

 

 

 
Synopsis

@@ -414,14 +534,35 @@ 
Synopsis

 
 
 explicit(false)
-ExplicitFalse(ExplicitFalse const&);
+ExplicitFalse(ExplicitFalse const& other);
 
 

 

+

+
Parameters

+
+
+
+
+
+
+
+
+
+
+
+
+
+
NameDescription
otherThe object to copy construct from

+

 

 

 

 
ExplicitFalse::ExplicitFalse

+

+Move constructor
+
+

 

 

 
Synopsis

@@ -430,14 +571,35 @@ 
Synopsis

 
 
 explicit(false)
-ExplicitFalse(ExplicitFalse&&) noexcept;
+ExplicitFalse(ExplicitFalse&& other) noexcept;
 
 

 

+

+
Parameters

+
+
+
+
+
+
+
+
+
+
+
+
+
+
NameDescription
otherThe object to move construct from

+

 

 

 

 
ExplicitFalse::ExplicitFalse

+

+Constructor
+
+

 

 

 
Synopsis

@@ -477,7 +639,7 @@ 
Member Functions

 
 
 
-ExplicitTrue         [constructor]
+ExplicitTrue         [constructor]Constructors
 
 
 
@@ -487,12 +649,16 @@ 
Member Functions

 

 

 
ExplicitTrue::ExplicitTrue

+

+Constructors
+
+

 

 

 
Synopses

 

 Declared in <explicit-ctor.cpp>

-
+Default constructor
 
 
 explicit(true)
@@ -500,23 +666,23 @@ 
Synopses

 
 
» more...
 
-
+Copy constructor
 
 
 explicit(true)
-ExplicitTrue(ExplicitTrue const&);
+ExplicitTrue(ExplicitTrue const& other);
 
 
» more...
 
-
+Move constructor
 
 
 explicit(true)
-ExplicitTrue(ExplicitTrue&&) noexcept;
+ExplicitTrue(ExplicitTrue&& other) noexcept;
 
 
» more...
 
-
+Constructor
 
 
 explicit(true)
@@ -532,6 +698,10 @@ 
Synopses

 

 

 
ExplicitTrue::ExplicitTrue

+

+Default constructor
+
+

 

 

 
Synopsis

@@ -548,6 +718,10 @@ 
Synopsis

 

 

 
ExplicitTrue::ExplicitTrue

+

+Copy constructor
+
+

 

 

 
Synopsis

@@ -556,14 +730,35 @@ 
Synopsis

 
 
 explicit(true)
-ExplicitTrue(ExplicitTrue const&);
+ExplicitTrue(ExplicitTrue const& other);
 
 

 

+

+
Parameters

+
+
+
+
+
+
+
+
+
+
+
+
+
+
NameDescription
otherThe object to copy construct from

+

 

 

 

 
ExplicitTrue::ExplicitTrue

+

+Move constructor
+
+

 

 

 
Synopsis

@@ -572,14 +767,35 @@ 
Synopsis

 
 
 explicit(true)
-ExplicitTrue(ExplicitTrue&&) noexcept;
+ExplicitTrue(ExplicitTrue&& other) noexcept;
 
 

 

+

+
Parameters

+
+
+
+
+
+
+
+
+
+
+
+
+
+
NameDescription
otherThe object to move construct from

+

 

 

 

 
ExplicitTrue::ExplicitTrue

+

+Constructor
+
+

 

 

 
Synopsis

diff --git a/test-files/golden-tests/symbols/function/explicit-ctor.xml b/test-files/golden-tests/symbols/function/explicit-ctor.xml
index 38c4b96d2..91753effa 100644
--- a/test-files/golden-tests/symbols/function/explicit-ctor.xml
+++ b/test-files/golden-tests/symbols/function/explicit-ctor.xml
@@ -6,22 +6,43 @@
     
     
       
+      
+        
+          Default constructor
+        
+      
     
     
       
-      
+      
         
           
         
       
+      
+        
+          Copy constructor
+        
+        
+          The object to copy construct from
+        
+      
     
     
       
-      
+      
         
           
         
       
+      
+        
+          Move constructor
+        
+        
+          The object to move construct from
+        
+      
     
     
       
@@ -31,6 +52,11 @@
       
         
       
+      
+        
+          Constructor
+        
+      
     
   
   
@@ -71,22 +123,43 @@
     
     
       
+      
+        
+          Default constructor
+        
+      
     
     
       
-      
+      
         
           
         
       
+      
+        
+          Copy constructor
+        
+        
+          The object to copy construct from
+        
+      
     
     
       
-      
+      
         
           
         
       
+      
+        
+          Move constructor
+        
+        
+          The object to move construct from
+        
+      
     
     
       
@@ -96,28 +169,54 @@
       
         
       
+      
+        
+          Constructor
+        
+      
     
   
   
     
     
       
+      
+        
+          Default constructor
+        
+      
     
     
       
-      
+      
         
           
         
       
+      
+        
+          Copy constructor
+        
+        
+          The object to copy construct from
+        
+      
     
     
       
-      
+      
         
           
         
       
+      
+        
+          Move constructor
+        
+        
+          The object to move construct from
+        
+      
     
     
       
@@ -127,6 +226,11 @@
       
         
       
+      
+        
+          Constructor
+        
+      
     
   
 
diff --git a/test-files/golden-tests/symbols/function/overloaded-op-1.adoc b/test-files/golden-tests/symbols/function/overloaded-op-1.adoc
index 3c1e01bf6..7e147a605 100644
--- a/test-files/golden-tests/symbols/function/overloaded-op-1.adoc
+++ b/test-files/golden-tests/symbols/function/overloaded-op-1.adoc
@@ -26,15 +26,19 @@ struct T;
 
 === Member Functions
 
-[cols=1]
+[cols=2]
 |===
 | Name
+| Description
 | <> 
+| Unary plus operator
 |===
 
 [#T-operator_plus]
 == <>::operator+
 
+Unary plus operator
+
 === Synopsis
 
 Declared in `<overloaded‐op‐1.cpp>`
@@ -45,5 +49,9 @@ Declared in `<overloaded‐op‐1.cpp>`
 operator+();
 ----
 
+=== Return Value
+
+Another instance of the object
+
 
 [.small]#Created with https://www.mrdocs.com[MrDocs]#
diff --git a/test-files/golden-tests/symbols/function/overloaded-op-1.html b/test-files/golden-tests/symbols/function/overloaded-op-1.html
index 8eba3939f..30091ef65 100644
--- a/test-files/golden-tests/symbols/function/overloaded-op-1.html
+++ b/test-files/golden-tests/symbols/function/overloaded-op-1.html
@@ -42,11 +42,12 @@ 
Member Functions

 
 
 Name
+Description
 
 
 
 
-operator+ 
+operator+ Unary plus operator
 
 
 
@@ -56,6 +57,10 @@ 
Member Functions

 

 

 
T::operator+

+

+Unary plus operator
+
+

 

 

 
Synopsis

@@ -68,6 +73,10 @@ 
Synopsis

 
 

 

+

+
Return Value

+Another instance of the object
+

 

 
 

diff --git a/test-files/golden-tests/symbols/function/overloaded-op-1.xml b/test-files/golden-tests/symbols/function/overloaded-op-1.xml
index 4d72f09ce..d9fb69982 100644
--- a/test-files/golden-tests/symbols/function/overloaded-op-1.xml
+++ b/test-files/golden-tests/symbols/function/overloaded-op-1.xml
@@ -10,6 +10,14 @@
       
         
       
+      
+        
+          Unary plus operator
+        
+        
+          Another instance of the object
+        
+      
     
   
 
diff --git a/test-files/golden-tests/symbols/function/overloaded-op-2.adoc b/test-files/golden-tests/symbols/function/overloaded-op-2.adoc
index 056451667..0ad4f8c2d 100644
--- a/test-files/golden-tests/symbols/function/overloaded-op-2.adoc
+++ b/test-files/golden-tests/symbols/function/overloaded-op-2.adoc
@@ -26,15 +26,19 @@ struct T;
 
 === Member Functions
 
-[cols=1]
+[cols=2]
 |===
 | Name
+| Description
 | <> 
+| Addition operator
 |===
 
 [#T-operator_plus]
 == <>::operator+
 
+Addition operator
+
 === Synopsis
 
 Declared in `<overloaded‐op‐2.cpp>`
@@ -42,8 +46,22 @@ Declared in `<overloaded‐op‐2.cpp>`
 [source,cpp,subs="verbatim,replacements,macros,-callouts"]
 ----
 <>
-operator+(<>);
+operator+(<> rhs);
 ----
 
+=== Return Value
+
+Another instance of the object
+
+=== Parameters
+
+[cols=2]
+|===
+| Name
+| Description
+| *rhs*
+| The right operand
+|===
+
 
 [.small]#Created with https://www.mrdocs.com[MrDocs]#
diff --git a/test-files/golden-tests/symbols/function/overloaded-op-2.html b/test-files/golden-tests/symbols/function/overloaded-op-2.html
index 3d21f5217..f82e273b7 100644
--- a/test-files/golden-tests/symbols/function/overloaded-op-2.html
+++ b/test-files/golden-tests/symbols/function/overloaded-op-2.html
@@ -42,11 +42,12 @@ 
Member Functions

 
 
 Name
+Description
 
 
 
 
-operator+ 
+operator+ Addition operator
 
 
 
@@ -56,6 +57,10 @@ 
Member Functions

 

 

 
T::operator+

+

+Addition operator
+
+

 

 

 
Synopsis

@@ -64,10 +69,31 @@ 
Synopsis

 
 
 T
-operator+(T);
+operator+(T rhs);
 
 

 

+

+
Return Value

+Another instance of the object
+

+

+
Parameters

+
+
+
+
+
+
+
+
+
+
+
+
+
+
NameDescription
rhsThe right operand

+

 

 
 

diff --git a/test-files/golden-tests/symbols/function/overloaded-op-2.xml b/test-files/golden-tests/symbols/function/overloaded-op-2.xml
index eb070590c..e43cf5091 100644
--- a/test-files/golden-tests/symbols/function/overloaded-op-2.xml
+++ b/test-files/golden-tests/symbols/function/overloaded-op-2.xml
@@ -10,9 +10,20 @@
       
         
       
-      
+      
         
       
+      
+        
+          Addition operator
+        
+        
+          Another instance of the object
+        
+        
+          The right operand
+        
+      
     
   
 
diff --git a/test-files/golden-tests/symbols/overloads/overloads-brief.adoc b/test-files/golden-tests/symbols/overloads/overloads-brief.adoc
index 3fc9ad5e7..5bf1e1920 100644
--- a/test-files/golden-tests/symbols/overloads/overloads-brief.adoc
+++ b/test-files/golden-tests/symbols/overloads/overloads-brief.adoc
@@ -57,7 +57,7 @@ struct A;
 | <> 
 | Addition operators
 | <> 
-| `operator‐` overloads
+| Unary minus operators
 |===
 
 === Non-Member Functions
@@ -156,27 +156,27 @@ Assignment operators
 
 Declared in `<overloads‐brief.cpp>`
 
-Assign from int
+Assign from A
 
 
 [source,cpp,subs="verbatim,replacements,macros,-callouts"]
 ----
 <>&
-<>(int a);
+<>(<> const& a);
 ----
 
-[.small]#<>#
+[.small]#<>#
 
-Assign from A
+Assign from int
 
 
 [source,cpp,subs="verbatim,replacements,macros,-callouts"]
 ----
 <>&
-<>(<> const& a);
+<>(int a);
 ----
 
-[.small]#<>#
+[.small]#<>#
 
 === Return Value
 
@@ -189,13 +189,13 @@ Assign from A
 | Name
 | Description
 | *a*
-| Describe b
+| Describe a
 |===
 
-[#A-operator_assign-06]
+[#A-operator_assign-04]
 == <>::operator=
 
-Assign from int
+Assign from A
 
 === Synopsis
 
@@ -204,7 +204,7 @@ Declared in `<overloads‐brief.cpp>`
 [source,cpp,subs="verbatim,replacements,macros,-callouts"]
 ----
 <>&
-operator=(int a);
+operator=(<> const& a);
 ----
 
 === Return Value
@@ -218,13 +218,13 @@ operator=(int a);
 | Name
 | Description
 | *a*
-| Describe b
+| Describe a
 |===
 
-[#A-operator_assign-04]
+[#A-operator_assign-06]
 == <>::operator=
 
-Assign from A
+Assign from int
 
 === Synopsis
 
@@ -233,7 +233,7 @@ Declared in `<overloads‐brief.cpp>`
 [source,cpp,subs="verbatim,replacements,macros,-callouts"]
 ----
 <>&
-operator=(<> const& a);
+operator=(int a);
 ----
 
 === Return Value
@@ -247,7 +247,7 @@ operator=(<> const& a);
 | Name
 | Description
 | *a*
-| Describe a
+| Describe b
 |===
 
 [#A-operator_plus-07]
@@ -356,7 +356,7 @@ operator+(<> const& a);
 [#A-operator_minus-0a]
 == <>::operator‐
 
-`operator‐` overloads
+Unary minus operators
 
 === Synopses
 
@@ -379,7 +379,7 @@ Binary operator‐ for A
 [source,cpp,subs="verbatim,replacements,macros,-callouts"]
 ----
 <>
-<>(<> const&);
+<>(<> const& rhs);
 ----
 
 [.small]#<>#
@@ -423,7 +423,7 @@ Declared in `<overloads‐brief.cpp>`
 [source,cpp,subs="verbatim,replacements,macros,-callouts"]
 ----
 <>
-operator‐(<> const&);
+operator‐(<> const& rhs);
 ----
 
 === Description
@@ -434,6 +434,16 @@ No way to generate a brief from the operator kind.
 
 Result
 
+=== Parameters
+
+[cols=2]
+|===
+| Name
+| Description
+| *rhs*
+| The right operand
+|===
+
 [#B]
 == B
 
@@ -554,7 +564,7 @@ Unary operator for A
 [source,cpp,subs="verbatim,replacements,macros,-callouts"]
 ----
 int
-<>(<> const&);
+<>(<> const& value);
 ----
 
 [.small]#<>#
@@ -565,7 +575,7 @@ Unary operator for B
 [source,cpp,subs="verbatim,replacements,macros,-callouts"]
 ----
 int
-<>(<> const&);
+<>(<> const& value);
 ----
 
 [.small]#<>#
@@ -586,13 +596,23 @@ Declared in `<overloads‐brief.cpp>`
 [source,cpp,subs="verbatim,replacements,macros,-callouts"]
 ----
 int
-operator+(<> const&);
+operator+(<> const& value);
 ----
 
 === Return Value
 
 Result
 
+=== Parameters
+
+[cols=2]
+|===
+| Name
+| Description
+| *value*
+| The operand
+|===
+
 [#operator_plus-06]
 == operator+
 
@@ -605,13 +625,23 @@ Declared in `<overloads‐brief.cpp>`
 [source,cpp,subs="verbatim,replacements,macros,-callouts"]
 ----
 int
-operator+(<> const&);
+operator+(<> const& value);
 ----
 
 === Return Value
 
 Result
 
+=== Parameters
+
+[cols=2]
+|===
+| Name
+| Description
+| *value*
+| The operand
+|===
+
 [#sameBrief-08]
 == sameBrief
 
diff --git a/test-files/golden-tests/symbols/overloads/overloads-brief.html b/test-files/golden-tests/symbols/overloads/overloads-brief.html
index 2bf38779d..7ab23146b 100644
--- a/test-files/golden-tests/symbols/overloads/overloads-brief.html
+++ b/test-files/golden-tests/symbols/overloads/overloads-brief.html
@@ -72,7 +72,7 @@ 
Member Functions

 A         [constructor]Constructors
 operator= Assignment operators
 operator+ Addition operators
-operator- operator- overloads
+operator- Unary minus operators
 
 
 
@@ -206,21 +206,21 @@ 
A::operator=

 
Synopses

 

 Declared in <overloads-brief.cpp>

-Assign from int
+Assign from A
 
 
 A&
-operator=(int a);
+operator=(A const& a);
 
-
» more...
+
» more...
 
-Assign from A
+Assign from int
 
 
 A&
-operator=(A const& a);
+operator=(int a);
 
-
» more...
+
» more...
 
 
 

@@ -240,7 +240,7 @@ 
Parameters

 
 
 a
-Describe b
+Describe a
 
 
 
@@ -248,9 +248,9 @@ 
Parameters

 

 

 

-
A::operator=

+
A::operator=

 

-Assign from int
+Assign from A
 
 

 

@@ -261,7 +261,7 @@ 
Synopsis

 
 
 A&
-operator=(int a);
+operator=(A const& a);
 
 

 

@@ -281,7 +281,7 @@ 
Parameters

 
 
 a
-Describe b
+Describe a
 
 
 
@@ -289,9 +289,9 @@ 
Parameters

 

 

 

-
A::operator=

+
A::operator=

 

-Assign from A
+Assign from int
 
 

 

@@ -302,7 +302,7 @@ 
Synopsis

 
 
 A&
-operator=(A const& a);
+operator=(int a);
 
 

 

@@ -322,7 +322,7 @@ 
Parameters

 
 
 a
-Describe a
+Describe b
 
 
 
@@ -466,7 +466,7 @@ 
Parameters

 

 
A::operator-

 

-operator- overloads
+Unary minus operators
 
 

 

@@ -486,7 +486,7 @@ 
Synopses

 
 
 A
-operator-(A const&);
+operator-(A const& rhs);
 
 
» more...
 
@@ -540,7 +540,7 @@ 
Synopsis

 
 
 A
-operator-(A const&);
+operator-(A const& rhs);
 
 

 

@@ -552,6 +552,23 @@ 
Description

 
Return Value

 Result
 

+

+
Parameters

+
+
+
+
+
+
+
+
+
+
+
+
+
+
NameDescription
rhsThe right operand

+

 

 

 

@@ -709,7 +726,7 @@ 
Synopses

 
 
 int
-operator+(A const&);
+operator+(A const& value);
 
 
» more...
 
@@ -717,7 +734,7 @@ 
Synopses

 
 
 int
-operator+(B const&);
+operator+(B const& value);
 
 
» more...
 
@@ -743,7 +760,7 @@ 
Synopsis

 
 
 int
-operator+(A const&);
+operator+(A const& value);
 
 

 

@@ -751,6 +768,23 @@ 
Synopsis

 
Return Value

 Result
 

+

+
Parameters

+
+
+
+
+
+
+
+
+
+
+
+
+
+
NameDescription
valueThe operand

+
@@ -767,7 +801,7 @@

Synopsis

 
 int
-operator+(B const&);
+operator+(B const& value);
@@ -775,6 +809,23 @@

Synopsis

Return Value

Result
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
valueThe operand
+
diff --git a/test-files/golden-tests/symbols/overloads/overloads-brief.xml b/test-files/golden-tests/symbols/overloads/overloads-brief.xml index d872733f0..a9e382a8a 100644 --- a/test-files/golden-tests/symbols/overloads/overloads-brief.xml +++ b/test-files/golden-tests/symbols/overloads/overloads-brief.xml @@ -34,8 +34,8 @@ - - + + @@ -43,22 +43,24 @@ - + + + - Assign from int + Assign from A *this - Describe b + Describe a - - + + @@ -66,19 +68,17 @@ - - - + - Assign from A + Assign from int *this - Describe a + Describe b @@ -150,7 +150,7 @@ - + @@ -165,6 +165,9 @@ Result + + The right operand + @@ -207,7 +210,7 @@ - + @@ -219,6 +222,9 @@ Result + + The operand + A @@ -230,7 +236,7 @@ - + @@ -242,6 +248,9 @@ Result + + The operand + B diff --git a/test-files/golden-tests/symbols/overloads/overloads-ostream.adoc b/test-files/golden-tests/symbols/overloads/overloads-ostream.adoc index 5d179b814..2024a3677 100644 --- a/test-files/golden-tests/symbols/overloads/overloads-ostream.adoc +++ b/test-files/golden-tests/symbols/overloads/overloads-ostream.adoc @@ -51,16 +51,20 @@ class A; | Name | Description | <> -| +| Left shift operators |=== [#left_shift-A-operator_lshift-06] == <>::<>::operator<< +Left shift operators + === Synopses Declared in `<overloads‐ostream.cpp>` +Left shift operator + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- @@ -70,6 +74,8 @@ Declared in `<overloads‐ostream.cpp>` [.small]#<># +Left shift operator + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- @@ -82,6 +88,8 @@ Declared in `<overloads‐ostream.cpp>` [#left_shift-A-operator_lshift-0f] == <>::<>::operator<< +Left shift operator + === Synopsis Declared in `<overloads‐ostream.cpp>` @@ -92,9 +100,25 @@ Declared in `<overloads‐ostream.cpp>` operator<<(unsigned int shift); ---- +=== Return Value + +Reference to the current object + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *shift* +| The right operand +|=== + [#left_shift-A-operator_lshift-0b] == <>::<>::operator<< +Left shift operator + === Synopsis Declared in `<overloads‐ostream.cpp>` @@ -105,6 +129,20 @@ Declared in `<overloads‐ostream.cpp>` operator<<(char shift); ---- +=== Return Value + +Reference to the current object + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *shift* +| The right operand +|=== + [#left_shift-operator_lshift] == <>::operator<< @@ -140,7 +178,7 @@ operator<<( | Name | Description | <> -| +| Stream insertion operators |=== [#ostream-B] @@ -175,8 +213,8 @@ Declared in `<overloads‐ostream.cpp>` friend <>& operator<<( - <>&, - <>); + <>& os, + <> value); ---- [#ostream-C] @@ -206,28 +244,34 @@ class OStream; [#ostream-operator_lshift-0f] == <>::operator<< +Stream insertion operators + === Synopses Declared in `<overloads‐ostream.cpp>` +Stream insertion operator + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- <>& <>( - <>&, - <>); + <>& os, + <> value); ---- [.small]#<># +Stream insertion operator + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- <>& <>( - <>&, - <>); + <>& os, + <> value); ---- [.small]#<># @@ -235,6 +279,8 @@ Declared in `<overloads‐ostream.cpp>` [#ostream-operator_lshift-0d] == <>::operator<< +Stream insertion operator + === Synopsis Declared in `<overloads‐ostream.cpp>` @@ -243,13 +289,31 @@ Declared in `<overloads‐ostream.cpp>` ---- <>& operator<<( - <>&, - <>); + <>& os, + <> value); ---- +=== Return Value + +Reference to the current output stream + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *os* +| An output stream +| *value* +| The object to output +|=== + [#ostream-operator_lshift-0a] == <>::operator<< +Stream insertion operator + === Synopsis Declared in `<overloads‐ostream.cpp>` @@ -258,9 +322,25 @@ Declared in `<overloads‐ostream.cpp>` ---- <>& operator<<( - <>&, - <>); + <>& os, + <> value); ---- +=== Return Value + +Reference to the current output stream + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *os* +| An output stream +| *value* +| The object to output +|=== + [.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/test-files/golden-tests/symbols/overloads/overloads-ostream.html b/test-files/golden-tests/symbols/overloads/overloads-ostream.html index 7a175b05d..506f1a9aa 100644 --- a/test-files/golden-tests/symbols/overloads/overloads-ostream.html +++ b/test-files/golden-tests/symbols/overloads/overloads-ostream.html @@ -79,7 +79,7 @@

Member Functions

-operator<< +operator<< Left shift operators @@ -89,12 +89,16 @@

Member Functions

left_shift::A::operator<<

+
+Left shift operators + +

Synopses

Declared in <overloads-ostream.cpp>
- +Left shift operator 
 
 A&
@@ -102,7 +106,7 @@ 
Synopses
» more... - +Left shift operator 
 
 A&
@@ -116,6 +120,10 @@ 
Synopses

 

 

 
left_shift::A::operator<<

+

+Left shift operator
+
+

 

 

 
Synopsis

@@ -128,10 +136,35 @@ 
Synopsis
+
+

Return Value

+Reference to the current object +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
shiftThe right operand
+

left_shift::A::operator<<

+
+Left shift operator + +

Synopsis

@@ -144,6 +177,27 @@

Synopsis
+
+

Return Value

+Reference to the current object +
+
+

Parameters

+ + + + + + + + + + + + + +
NameDescription
shiftThe right operand
+
@@ -192,7 +246,7 @@

Functions

-operator<< +operator<< Stream insertion operators @@ -240,8 +294,8 @@

Synopsis

friend OStream& operator<<( - OStream&, - B); + OStream& os, + B value);
@@ -283,28 +337,32 @@

Synopsis

ostream::operator<<

+
+Stream insertion operators + +

Synopses

Declared in <overloads-ostream.cpp>
- +Stream insertion operator 
 
 OStream&
 operator<<(
-    OStream&,
-    B);
+    OStream& os,
+    B value);
» more... - +Stream insertion operator 
 
 OStream&
 operator<<(
-    OStream&,
-    C);
+    OStream& os,
+    C value);
» more... @@ -314,6 +372,10 @@

Synopses

ostream::operator<<

+
+Stream insertion operator + +

Synopsis

@@ -323,15 +385,44 @@

Synopsis

OStream& operator<<( - OStream&, - B); + OStream& os, + B value);
+
+

Return Value

+Reference to the current output stream +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
osAn output stream
valueThe object to output
+

ostream::operator<<

+
+Stream insertion operator + +

Synopsis

@@ -341,11 +432,36 @@

Synopsis

OStream& operator<<( - OStream&, - C); + OStream& os, + C value);
+
+

Return Value

+Reference to the current output stream +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
osAn output stream
valueThe object to output
+
diff --git a/test-files/golden-tests/symbols/overloads/overloads-ostream.xml b/test-files/golden-tests/symbols/overloads/overloads-ostream.xml index 3fe0f6d5b..179e8cc71 100644 --- a/test-files/golden-tests/symbols/overloads/overloads-ostream.xml +++ b/test-files/golden-tests/symbols/overloads/overloads-ostream.xml @@ -16,6 +16,17 @@ + + + Left shift operator + + + Reference to the current object + + + The right operand + + @@ -28,6 +39,17 @@ + + + Left shift operator + + + Reference to the current object + + + The right operand + + @@ -68,14 +90,28 @@ - + - + + + + Stream insertion operator + + + Reference to the current output stream + + + An output stream + + + The object to output + + @@ -85,14 +121,28 @@ - + - + + + + Stream insertion operator + + + Reference to the current output stream + + + An output stream + + + The object to output + + diff --git a/test-files/golden-tests/symbols/overloads/overloads.adoc b/test-files/golden-tests/symbols/overloads/overloads.adoc index c863dc128..a7d444fa9 100644 --- a/test-files/golden-tests/symbols/overloads/overloads.adoc +++ b/test-files/golden-tests/symbols/overloads/overloads.adoc @@ -22,7 +22,7 @@ | <> | | <> -| +| Equality operators |=== [#A] @@ -184,8 +184,8 @@ Declared in `<overloads.cpp>` friend bool operator==( - <>, - <>); + <> lhs, + <> rhs); ---- [#A-08friend-0e] @@ -200,8 +200,8 @@ Declared in `<overloads.cpp>` friend bool operator==( - <>, - int); + <> lhs, + int rhs); ---- [#B] @@ -270,50 +270,60 @@ f(int); [#operator_eq-0d] == operator== +Equality operators + === Synopses Declared in `<overloads.cpp>` +Equality operator + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- bool <>( - <>, - <>); + <> lhs, + <> rhs); ---- [.small]#<># +Equality operator + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- bool <>( - <>, - int); + <> lhs, + int rhs); ---- [.small]#<># +Equality operator + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- bool <>( - <>, - <>); + <> lhs, + <> rhs); ---- [.small]#<># +Equality operator + [source,cpp,subs="verbatim,replacements,macros,-callouts"] ---- bool <>( - <>, - int); + <> lhs, + int rhs); ---- [.small]#<># @@ -321,6 +331,8 @@ bool [#operator_eq-0a] == operator== +Equality operator + === Synopsis Declared in `<overloads.cpp>` @@ -329,13 +341,31 @@ Declared in `<overloads.cpp>` ---- bool operator==( - <>, - <>); + <> lhs, + <> rhs); ---- +=== Return Value + +`true` if the objects are equal, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *lhs* +| The left operand +| *rhs* +| The right operand +|=== + [#operator_eq-0e] == operator== +Equality operator + === Synopsis Declared in `<overloads.cpp>` @@ -344,13 +374,31 @@ Declared in `<overloads.cpp>` ---- bool operator==( - <>, - int); + <> lhs, + int rhs); ---- +=== Return Value + +`true` if the objects are equal, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *lhs* +| The left operand +| *rhs* +| The right operand +|=== + [#operator_eq-08] == operator== +Equality operator + === Synopsis Declared in `<overloads.cpp>` @@ -359,13 +407,31 @@ Declared in `<overloads.cpp>` ---- bool operator==( - <>, - <>); + <> lhs, + <> rhs); ---- +=== Return Value + +`true` if the objects are equal, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *lhs* +| The left operand +| *rhs* +| The right operand +|=== + [#operator_eq-07] == operator== +Equality operator + === Synopsis Declared in `<overloads.cpp>` @@ -374,9 +440,25 @@ Declared in `<overloads.cpp>` ---- bool operator==( - <>, - int); + <> lhs, + int rhs); ---- +=== Return Value + +`true` if the objects are equal, `false` otherwise + +=== Parameters + +[cols=2] +|=== +| Name +| Description +| *lhs* +| The left operand +| *rhs* +| The right operand +|=== + [.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/test-files/golden-tests/symbols/overloads/overloads.html b/test-files/golden-tests/symbols/overloads/overloads.html index fbf589cda..06aa6cc6d 100644 --- a/test-files/golden-tests/symbols/overloads/overloads.html +++ b/test-files/golden-tests/symbols/overloads/overloads.html @@ -34,7 +34,7 @@

Functions

f -operator== +operator== Equality operators @@ -233,8 +233,8 @@

Synopsis

friend bool operator==( - A, - A); + A lhs, + A rhs);
@@ -252,8 +252,8 @@

Synopsis

friend bool operator==( - A, - int); + A lhs, + int rhs);
@@ -337,48 +337,52 @@

Synopsis

operator==

+
+Equality operators + +

Synopses

Declared in <overloads.cpp>
- +Equality operator 
 
 bool
 operator==(
-    A,
-    A);
+    A lhs,
+    A rhs);
» more... - +Equality operator 
 
 bool
 operator==(
-    A,
-    int);
+    A lhs,
+    int rhs);
» more... - +Equality operator 
 
 bool
 operator==(
-    B,
-    B);
+    B lhs,
+    B rhs);
» more... - +Equality operator 
 
 bool
 operator==(
-    B,
-    int);
+    B lhs,
+    int rhs);
» more... @@ -388,6 +392,10 @@

Synopses

operator==

+
+Equality operator + +

Synopsis

@@ -397,15 +405,44 @@

Synopsis

bool operator==( - A, - A); + A lhs, + A rhs);
+
+

Return Value

+true if the objects are equal, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
lhsThe left operand
rhsThe right operand
+

operator==

+
+Equality operator + +

Synopsis

@@ -415,15 +452,44 @@

Synopsis

bool operator==( - A, - int); + A lhs, + int rhs);
+
+

Return Value

+true if the objects are equal, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
lhsThe left operand
rhsThe right operand
+

operator==

+
+Equality operator + +

Synopsis

@@ -433,15 +499,44 @@

Synopsis

bool operator==( - B, - B); + B lhs, + B rhs);
+
+

Return Value

+true if the objects are equal, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
lhsThe left operand
rhsThe right operand
+

operator==

+
+Equality operator + +

Synopsis

@@ -451,11 +546,36 @@

Synopsis

bool operator==( - B, - int); + B lhs, + int rhs);
+
+

Return Value

+true if the objects are equal, false otherwise +
+
+

Parameters

+ + + + + + + + + + + + + + + + + +
NameDescription
lhsThe left operand
rhsThe right operand
+
diff --git a/test-files/golden-tests/symbols/overloads/overloads.xml b/test-files/golden-tests/symbols/overloads/overloads.xml index 1cba3fa7e..8f3a3a531 100644 --- a/test-files/golden-tests/symbols/overloads/overloads.xml +++ b/test-files/golden-tests/symbols/overloads/overloads.xml @@ -60,12 +60,29 @@ - + - + + + + Equality operator + + + true + if the objects are equal, + false + otherwise + + + The left operand + + + The right operand + + @@ -73,12 +90,29 @@ - + - + + + + Equality operator + + + true + if the objects are equal, + false + otherwise + + + The left operand + + + The right operand + + @@ -86,12 +120,29 @@ - + - + + + + Equality operator + + + true + if the objects are equal, + false + otherwise + + + The left operand + + + The right operand + + @@ -99,12 +150,29 @@ - + - + + + + Equality operator + + + true + if the objects are equal, + false + otherwise + + + The left operand + + + The right operand + +