doc.hpp

Go to the documentation of this file.

#pragma once
#include <array>
#include <concepts>
#include <meta>
#include <span>
#include <string>
#include <string_view>
#include <vector>
 
#include <welder/concepts.hpp> // the doc_style concept (over function_doc, below)

 
namespace welder::inline v0 {

consteval std::string cleandoc(std::string_view text) {
    std::vector<std::string> lines{};
    std::string cur{};
    for (char c : text) {
        if (c == '\n') {
            lines.push_back(cur);
            cur.clear();
        } else
            cur.push_back(c);
    }
    lines.push_back(cur);
 
    auto leading = [](const std::string& s) {
        std::string::size_type n{0};
        while (n < s.size() && (s[n] == ' ' || s[n] == '\t'))
            ++n;
        return n;
    };
    auto blank = [](const std::string& s) {
        for (char c : s)
            if (c != ' ' && c != '\t' && c != '\r')
                return false;
        return true;
    };
 
    // Common leading whitespace of the lines *after* the first (blank lines don't
    // constrain it), which is what gets removed from those lines.
    bool have_margin{false};
    std::string::size_type margin{0};
    for (std::string::size_type i{1}; i < lines.size(); ++i)
        if (!blank(lines[i])) {
            const auto ind{leading(lines[i])};
            if (!have_margin || ind < margin) {
                margin = ind;
                have_margin = true;
            }
        }
 
    if (!lines.empty())
        lines[0].erase(0, leading(lines[0]));
    if (have_margin)
        for (std::string::size_type i{1}; i < lines.size(); ++i)
            lines[i].erase(0, margin); // over-erasing a short blank line is fine
 
    while (!lines.empty() && blank(lines.back()))
        lines.pop_back();
    while (!lines.empty() && blank(lines.front()))
        lines.erase(lines.begin());
 
    std::string out{};
    for (std::string::size_type i{0}; i < lines.size(); ++i) {
        if (i)
            out.push_back('\n');
        out += lines[i];
    }
    return out;
}

template <std::meta::info Ent, std::meta::info SpecTmpl>
consteval const char* annotation_text_of() {
    template for (constexpr auto a :
                  std::define_static_array(std::meta::annotations_of(Ent))) {
        constexpr std::meta::info t{std::meta::type_of(a)};
        if constexpr (std::meta::has_template_arguments(t) &&
                      std::meta::template_of(t) == SpecTmpl) {
            using spec_type = [:t:];
            constexpr auto spec{std::meta::extract<spec_type>(a)};
            return std::define_static_string(cleandoc(spec.text.data));
        }
    }
    return nullptr;
}

template <std::meta::info Ent>
consteval const char* doc_of() {
    return annotation_text_of<Ent, ^^detail::doc_spec>();
}

template <std::meta::info Fn>
consteval const char* return_doc_of() {
    return annotation_text_of<Fn, ^^detail::return_doc_spec>();
}
 
namespace detail {
struct tparam_doc {
    const char* name{nullptr}; 
    const char* text{nullptr}; 
};
} // namespace detail

template <std::meta::info Ent>
consteval size_type tparam_count() {
    size_type n{0};
    for (auto a : std::meta::annotations_of(Ent)) {
        auto t{std::meta::type_of(a)};
        if (std::meta::has_template_arguments(t) &&
            std::meta::template_of(t) == ^^detail::tparam_spec)
            ++n;
    }
    return n;
}

template <std::meta::info Ent>
consteval auto tparam_docs() {
    std::array<detail::tparam_doc, tparam_count<Ent>()> out{};
    size_type i{0};
    template for (constexpr auto a :
                  std::define_static_array(std::meta::annotations_of(Ent))) {
        constexpr std::meta::info t{std::meta::type_of(a)};
        if constexpr (std::meta::has_template_arguments(t) &&
                      std::meta::template_of(t) == ^^detail::tparam_spec) {
            using spec_type = [:t:];
            constexpr auto spec{std::meta::extract<spec_type>(a)};
            out[i++] = detail::tparam_doc{std::define_static_string(spec.name.data),
                                          std::define_static_string(spec.text.data)};
        }
    }
    return out;
}
 
namespace detail {
struct param_doc {
    const char* name{nullptr}; 
    const char* text{nullptr}; 
};
} // namespace detail

template <std::meta::info Fn>
consteval auto param_docs() {
    constexpr size_type n{std::meta::parameters_of(Fn).size()};
    std::array<detail::param_doc, n> out{};
    // The final `i++` in the unrolled `template for` is a dead store (its result is
    // never read), which trips -Wunused-but-set-variable; the counter is genuinely
    // used to index `out`, so mark it maybe_unused rather than restructure.
    [[maybe_unused]] size_type i{0};
    template for (constexpr auto p :
                  std::define_static_array(std::meta::parameters_of(Fn))) {
        const char* name{std::meta::has_identifier(p)
                             ? std::define_static_string(std::meta::identifier_of(p))
                             : nullptr};
        out[i++] = detail::param_doc{name, doc_of<p>()};
    }
    return out;
}
 
// --- docstring styles -------------------------------------------------------
 
namespace detail {
struct function_doc {
    const char* summary{nullptr};        
    std::span<const param_doc> params{}; 
    const char* returns{nullptr};        
};
} // namespace detail
 
// The `doc_style` concept — the customization point that folds a `function_doc`
// into one docstring — lives in <welder/concepts.hpp> (with welder's other
// interface concepts); `function_docstring` below constrains its `Style` on it.

template <std::meta::info Fn, doc_style Style>
std::string function_docstring() {
    static constexpr auto pds{param_docs<Fn>()};
    return Style::format(detail::function_doc{doc_of<Fn>(),
                                              std::span<const detail::param_doc>{pds},
                                              return_doc_of<Fn>()});
}
 
} // namespace welder