Skip to content

javadoc mapping traits #878

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 12, 2025
Merged

javadoc mapping traits #878

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
795 changes: 783 additions & 12 deletions include/mrdocs/Metadata/Javadoc.hpp
View file
Open in desktop

Large diffs are not rendered by default.

25 changes: 23 additions & 2 deletions include/mrdocs/Support/Algorithm.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,6 @@ contains(Range const& range, El const& el)
std::ranges::end(range), el) != std::ranges::end(range);
}

// A second overload where the range is an initializer list

/** Determine if a range contains a specific element.
@param range The range to search.
@param el The element to search for.
Expand All @@ -49,6 +47,29 @@ contains(std::initializer_list<T> const& range, U const& el)
std::ranges::end(range), el) != std::ranges::end(range);
}

/** Determine if an element is equal to any of the elements in the specified range.

@param el The element to search for.
@param range The range to search.
@return True if the element is found, false otherwise.
*/
template <class El, std::ranges::range Range>
requires std::equality_comparable_with<std::ranges::range_value_t<Range>, El>
bool
is_one_of(El const& el, Range const& range)
{
return contains(range, el);
}

/// @copydoc is_one_of(El const&, Range const&)
template <class U, class T>
requires std::equality_comparable_with<U, T>
bool
is_one_of(U const& el, std::initializer_list<T> const& range)
{
return contains(range, el);
}

/** Determine if a range contains any of the specified elements.
@param range The range to search.
@param els The elements to search for.
Expand Down
9 changes: 9 additions & 0 deletions include/mrdocs/Support/Concepts.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,15 @@ concept polymorphic_storage_for = requires(T const& t)
{ t.operator->() } -> std::convertible_to<Base const*>;
};

/** Determine if a type is dereferenceable

This concept checks if a type can be dereferenced
to a value it represents and converted to a boolean
value that represents if the object is in a valid state.

Examples of such types are std::optional, std::unique_ptr,
std::shared_ptr, Polymorphic, pointers, etc.
*/
template <class T>
concept dereferenceable = requires(T const& t)
{
Expand Down
94 changes: 62 additions & 32 deletions include/mrdocs/Support/String.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,58 +17,72 @@
#include <string>
#include <string_view>

namespace clang {
namespace mrdocs {
namespace clang::mrdocs {

/** Return the substring without leading specified characters.
*/
constexpr
std::string_view
ltrim(
std::string_view const s,
std::string_view const chars) noexcept
{
return s.substr(std::min(s.find_first_not_of(chars), s.size()));
}

/** Return the substring without leading horizontal whitespace.
*/
constexpr
std::string_view
ltrim(std::string_view s) noexcept
ltrim(
std::string_view const s) noexcept
{
auto it = s.begin();
for (;; ++it)
return ltrim(s, " \t\n\v\f\r");
}

/** Return the substring without trailing specified characters.
*/
constexpr
std::string_view
rtrim(
std::string_view const s,
std::string_view const chars) noexcept
{
auto const pos = s.find_last_not_of(chars);
if (pos == std::string_view::npos)
{
if (it == s.end())
return {};
if (! std::isspace(*it))
break;
return s.substr(0, 0);
}
return s.substr(it - s.begin());
return s.substr(0, pos + 1);
}

/** Return the substring without trailing horizontal whitespace.
*/
constexpr
std::string_view
rtrim(std::string_view s) noexcept
rtrim(std::string_view const s) noexcept
{
auto it = s.end() - 1;
while(it > s.begin() && std::isspace(*it))
{
--it;
}
return s.substr(0, it - s.begin() + 1);
return rtrim(s, " \t\n\v\f\r");
}

/** Return the substring without leading and trailing horizontal whitespace.
*/
constexpr
std::string_view
trim(std::string_view s) noexcept
trim(std::string_view const s) noexcept
{
auto left = s.begin();
for (;; ++left)
{
if (left == s.end())
return {};
if (!isspace(*left))
break;
}
auto right = s.end() - 1;
while(right > left && std::isspace(*right))
--right;
return std::string_view(&*left, right - left + 1);
return rtrim(ltrim(s));
}

/** Return the substring without leading and trailing specified characters.
*/
constexpr
std::string_view
trim(
std::string_view const s,
std::string_view const chars) noexcept
{
return rtrim(ltrim(s, chars), chars);
}

/** Return the substring without leading and trailing horizontal whitespace.
Expand All @@ -86,8 +100,24 @@ isWhitespace(std::string_view s) noexcept
return s.find_first_not_of(" \t\n\v\f\r") == std::string::npos;
}

/** Determine if a string starts with one of the specified characters
*/
constexpr
bool
startsWithOneOf(std::string_view s, std::string_view chars) noexcept
{
return !s.empty() && chars.find(s.front()) != std::string_view::npos;
}

/** Determine if a string ends with one of the specified characters
*/
constexpr
bool
endsWithOneOf(std::string_view s, std::string_view chars) noexcept
{
return !s.empty() && chars.find(s.back()) != std::string_view::npos;
}

} // mrdocs
} // clang
} // clang::mrdocs

#endif
3 changes: 3 additions & 0 deletions share/mrdocs/addons/generator/adoc/partials/javadoc/admonition.adoc.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
[{{upper admonish}}]
{{#each children}}{{> javadoc/any-text }}{{/each}}

5 changes: 5 additions & 0 deletions share/mrdocs/addons/generator/adoc/partials/javadoc/code.adoc.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
[,cpp]
----
{{#each children}}{{> javadoc/any-text verbatim=true }}
{{/each}}
----
2 changes: 2 additions & 0 deletions share/mrdocs/addons/generator/adoc/partials/javadoc/detail-blocks.adoc.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
{{#each .}}{{>javadoc/any-block .}}{{/each}}

3 changes: 3 additions & 0 deletions share/mrdocs/addons/generator/adoc/partials/javadoc/heading.adoc.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@

=== {{string}}

2 changes: 2 additions & 0 deletions share/mrdocs/addons/generator/adoc/partials/javadoc/paragraph.adoc.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
{{#each children}}{{> javadoc/any-text }}{{/each}}

3 changes: 3 additions & 0 deletions share/mrdocs/addons/generator/adoc/partials/javadoc/unordered_list.adoc.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{{#each items}}* {{> javadoc/block }}
{{/each}}

1 change: 1 addition & 0 deletions share/mrdocs/addons/generator/adoc/partials/markup/b.adoc.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
*{{> @partial-block }}*
1 change: 1 addition & 0 deletions share/mrdocs/addons/generator/adoc/partials/markup/i.adoc.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
_{{> @partial-block }}_
6 changes: 5 additions & 1 deletion share/mrdocs/addons/generator/adoc/partials/markup/span.adoc.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1,5 @@
{{#if class}}[.{{class}}]#{{/if}}{{> @partial-block }}{{#if class}}#{{/if}}
{{#unless class~}}
{{> @partial-block }}
{{~else~}}
[.{{class}}]#{{> @partial-block }}#
{{~/unless}}
40 changes: 24 additions & 16 deletions share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@

{{! Brief }}
{{#if symbol.doc.brief}}
{{{symbol.doc.brief}}}
{{> javadoc/brief symbol.doc.brief }}


{{/if}}
{{! Synopsis }}
Expand Down Expand Up @@ -60,7 +61,7 @@
{{else}}
|`{{>symbol/name . nolink=true}}`
{{/if}}
|{{{~ doc.brief }}}
|{{> javadoc/brief doc.brief }}
{{/each}}
|===

Expand All @@ -77,11 +78,10 @@

{{/if}}
{{! Description }}
{{#if symbol.doc.description}}
{{#if symbol.doc.details}}
{{#> markup/dynamic-level-h }}Description{{/markup/dynamic-level-h}}

{{{symbol.doc.description}}}

{{> javadoc/detail-blocks symbol.doc.details }}
{{/if}}
{{! Using symbols }}
{{#if symbol.shadows}}
Expand All @@ -103,8 +103,8 @@
| Name | Thrown on

{{#each symbol.doc.exceptions}}
| `{{exception}}`
| {{{description}}}
| {{> javadoc/reference exception}}
| {{>javadoc/block .}}

{{/each}}
|===
Expand All @@ -115,10 +115,11 @@
{{#> markup/dynamic-level-h }}Return Value{{/markup/dynamic-level-h}}

{{#if (eq (size symbol.doc.returns) 1)}}
{{{symbol.doc.returns.[0]}}}
{{> javadoc/returns symbol.doc.returns.[0]}}

{{else}}
{{#each symbol.doc.returns}}
* {{{.}}}
* {{> javadoc/returns .}}
{{/each}}
{{/if}}

Expand All @@ -132,7 +133,7 @@

{{#each symbol.doc.tparams}}
| *{{name}}*
| {{{description}}}
| {{>javadoc/block .}}

{{/each}}
|===
Expand All @@ -147,7 +148,7 @@

{{#each symbol.doc.params}}
| *{{name}}*{{#if direction}} [{{direction}}]{{/if}}
| {{{description}}}
| {{>javadoc/block .}}

{{/each}}
|===
Expand All @@ -158,26 +159,33 @@
{{#> markup/dynamic-level-h }}Preconditions{{/markup/dynamic-level-h}}

{{#each symbol.doc.preconditions}}
* {{{.}}}
* {{>javadoc/block .}}
{{/each}}



{{/if}}
{{! Postconditions }}
{{#if symbol.doc.postconditions}}
{{#> markup/dynamic-level-h }}Postconditions{{/markup/dynamic-level-h}}

{{#each symbol.doc.postconditions}}
* {{{.}}}
* {{>javadoc/block .}}
{{/each}}



{{/if}}
{{! See Also }}
{{#if symbol.doc.see}}
{{#if symbol.doc.sees}}
{{#> markup/dynamic-level-h }}See Also{{/markup/dynamic-level-h}}

{{#each symbol.doc.see}}
{{{.}}}
{{#each symbol.doc.sees}}
{{>javadoc/block .}}

{{/each}}




{{/if}}
1 change: 1 addition & 0 deletions share/mrdocs/addons/generator/common/partials/javadoc/any-block.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{{> (concat 'javadoc/' kind) }}
1 change: 1 addition & 0 deletions share/mrdocs/addons/generator/common/partials/javadoc/any-text.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{{> (concat 'javadoc/' kind) }}
1 change: 1 addition & 0 deletions share/mrdocs/addons/generator/common/partials/javadoc/block.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{{#>markup/span class=undefined}}{{#each children}}{{>javadoc/any-text }}{{/each}}{{/markup/span}}
1 change: 1 addition & 0 deletions share/mrdocs/addons/generator/common/partials/javadoc/brief.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{{>javadoc/block}}
1 change: 1 addition & 0 deletions share/mrdocs/addons/generator/common/partials/javadoc/details.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{{>javadoc/paragraph}}
1 change: 1 addition & 0 deletions share/mrdocs/addons/generator/common/partials/javadoc/link.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{{#>markup/a href=href}}{{> javadoc/block }}{{/markup/a}}
5 changes: 5 additions & 0 deletions share/mrdocs/addons/generator/common/partials/javadoc/reference.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{{#if symbol.url~}}
{{#>markup/a href=symbol.url}}{{#>markup/code}}{{string}}{{/markup/code}}{{/markup/a}}
{{~else~}}
{{#>markup/code}}{{string}}{{/markup/code}}
{{~/if}}
1 change: 1 addition & 0 deletions share/mrdocs/addons/generator/common/partials/javadoc/returns.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{{>javadoc/block}}
1 change: 1 addition & 0 deletions share/mrdocs/addons/generator/common/partials/javadoc/styled.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{{> (concat 'javadoc/styled/' style) }}
1 change: 1 addition & 0 deletions share/mrdocs/addons/generator/common/partials/javadoc/styled/bold.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{{#> markup/b }}{{string}}{{/ markup/b }}
1 change: 1 addition & 0 deletions share/mrdocs/addons/generator/common/partials/javadoc/styled/italic.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{{#> markup/i }}{{string}}{{/ markup/i }}
1 change: 1 addition & 0 deletions share/mrdocs/addons/generator/common/partials/javadoc/styled/mono.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{{#> markup/code }}{{string}}{{/ markup/code }}
1 change: 1 addition & 0 deletions share/mrdocs/addons/generator/common/partials/javadoc/text.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{{#unless verbatim}}{{string}}{{else}}{{{string}}}{{/unless}}
2 changes: 1 addition & 1 deletion share/mrdocs/addons/generator/common/partials/symbol/detail/members-table-row.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
{{~/markup/td}}
{{#if includeBrief~}}
{{~#>markup/td~}}
{{{~doc.brief~}}}
{{~> javadoc/brief doc.brief~}}
{{~/markup/td}}
{{/if}}

Expand Down
2 changes: 1 addition & 1 deletion share/mrdocs/addons/generator/common/partials/symbol/signatures.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@

{{else}}
{{#each members as | member |}}
{{#if member.doc.brief}}{{#> markup/p }}{{{member.doc.brief}}}{{/markup/p}}{{/if}}
{{#if member.doc.brief}}{{#> markup/p }}{{> javadoc/brief member.doc.brief }}{{/markup/p}}{{/if}}

{{#> markup/code-block }}
{{> symbol/signature member link=member}}
Expand Down
Loading
Loading