doc_style.hpp

Go to the documentation of this file.

#pragma once
#include <span>
#include <string>
#include <string_view>
 
#include <welder/doc.hpp> // detail::function_doc / detail::param_doc / doc_style concept

 
namespace welder::inline v0::rods::python {
 
namespace detail {

constexpr void append_indented(std::string& out, const char* text,
                               std::string_view indent) {
    for (const char* c{text}; *c; ++c) {
        out += *c;
        if (*c == '\n' && c[1] != '\0')
            out += indent;
    }
}

constexpr void blank_line(std::string& out) {
    if (!out.empty()) {
        if (out.back() != '\n')
            out += '\n';
        out += '\n';
    }
}

constexpr bool any_param_doc(const ::welder::detail::function_doc& d) {
    for (const auto& p : d.params)
        if (p.text)
            return true;
    return false;
}
 
} // namespace detail

struct google_style {
    static constexpr std::string format(const ::welder::detail::function_doc& d) {
        std::string out{};
        if (d.summary)
            out += d.summary;
 
        if (detail::any_param_doc(d)) {
            detail::blank_line(out);
            out += "Args:\n";
            for (const auto& p : d.params)
                if (p.text) {
                    out += "    ";
                    out += p.name ? p.name : "?";
                    out += ": ";
                    detail::append_indented(out, p.text, "        ");
                    out += '\n';
                }
        }
 
        if (d.returns) {
            detail::blank_line(out);
            out += "Returns:\n    ";
            detail::append_indented(out, d.returns, "    ");
        }
        return out;
    }

    static constexpr std::string format_enum(const ::welder::detail::enum_doc& e) {
        std::string out{};
        if (e.summary)
            out += e.summary;
 
        if (!e.members.empty()) {
            detail::blank_line(out);
            out += "Attributes:\n";
            for (const auto& m : e.members) {
                out += "    ";
                out += m.name;
                out += ": ";
                detail::append_indented(out, m.text, "        ");
                out += '\n';
            }
        }
        return out;
    }
};
 
static_assert(::welder::doc_style<google_style>);

struct numpy_style {
    static constexpr std::string format(const ::welder::detail::function_doc& d) {
        std::string out{};
        // Append an underlined section header (`title` then a rule of matching
        // length), separated from prior content by a blank line.
        auto section = [&out](std::string_view title) {
            detail::blank_line(out);
            out += title;
            out += '\n';
            out.append(title.size(), '-');
            out += '\n';
        };
 
        if (d.summary)
            out += d.summary;
 
        if (detail::any_param_doc(d)) {
            section("Parameters");
            for (const auto& p : d.params)
                if (p.text) {
                    out += p.name ? p.name : "?";
                    out += "\n    ";
                    detail::append_indented(out, p.text, "    ");
                    out += '\n';
                }
        }
 
        if (d.returns) {
            section("Returns");
            detail::append_indented(out, d.returns, "");
        }
        return out;
    }

    static constexpr std::string format_enum(const ::welder::detail::enum_doc& e) {
        std::string out{};
        if (e.summary)
            out += e.summary;
 
        if (!e.members.empty()) {
            detail::blank_line(out);
            out += "Attributes\n";
            out.append(std::string_view{"Attributes"}.size(), '-');
            out += '\n';
            for (const auto& m : e.members) {
                out += m.name;
                out += "\n    ";
                detail::append_indented(out, m.text, "    ");
                out += '\n';
            }
        }
        return out;
    }
};
 
static_assert(::welder::doc_style<numpy_style>);

struct sphinx_style {
    static constexpr std::string format(const ::welder::detail::function_doc& d) {
        std::string out{};
        if (d.summary)
            out += d.summary;
 
        const bool any_field{detail::any_param_doc(d) || d.returns};
        if (any_field)
            detail::blank_line(out);
 
        for (const auto& p : d.params)
            if (p.text) {
                out += ":param ";
                out += p.name ? p.name : "?";
                out += ": ";
                detail::append_indented(out, p.text, "    ");
                out += '\n';
            }
 
        if (d.returns) {
            out += ":returns: ";
            detail::append_indented(out, d.returns, "    ");
        }
        return out;
    }

    static constexpr std::string format_enum(const ::welder::detail::enum_doc& e) {
        std::string out{};
        if (e.summary)
            out += e.summary;
 
        if (!e.members.empty())
            detail::blank_line(out);
 
        for (const auto& m : e.members) {
            out += ":var ";
            out += m.name;
            out += ": ";
            detail::append_indented(out, m.text, "    ");
            out += '\n';
        }
        return out;
    }
};
 
static_assert(::welder::doc_style<sphinx_style>);
 
} // namespace welder::rods::python