From 5f9e5a136c171fc97b19fa18ea8b6c95748c145b Mon Sep 17 00:00:00 2001 From: alandefreitas Date: Wed, 13 Nov 2024 14:32:44 -0300 Subject: [PATCH] refactor(HandlebarsGenerator): remove unused options --- docs/mrdocs.schema.json | 6 +++ src/lib/Gen/hbs/Builder.cpp | 6 ++- src/lib/Gen/hbs/Builder.hpp | 45 +++++++++++++-------- src/lib/Gen/hbs/HandlebarsCorpus.hpp | 11 ++--- src/lib/Gen/hbs/HandlebarsGenerator.cpp | 33 --------------- src/lib/Gen/hbs/HandlebarsGenerator.hpp | 1 - src/lib/Gen/hbs/Options.hpp | 53 ------------------------- src/lib/Lib/ConfigOptions.json | 7 ++++ 8 files changed, 49 insertions(+), 113 deletions(-) delete mode 100644 src/lib/Gen/hbs/Options.hpp diff --git a/docs/mrdocs.schema.json b/docs/mrdocs.schema.json index b77be7d54..cb001875b 100644 --- a/docs/mrdocs.schema.json +++ b/docs/mrdocs.schema.json @@ -168,6 +168,12 @@ "title": "Include files to extract", "type": "object" }, + "legible-names": { + "default": true, + "description": "Use legible names for ids in the documentation. When set to true, MrDocs uses legible names for symbols in the documentation. These are symbols that are legible but still safe for URLs. When the option is set to false, MrDocs uses a hash of the symbol ID.", + "title": "Use legible names", + "type": "boolean" + }, "multipage": { "default": true, "description": "Generates a multipage documentation. The output directory must be a directory. This option acts as a hint to the generator to create a multipage documentation. Whether the hint is followed or not depends on the generator.", diff --git a/src/lib/Gen/hbs/Builder.cpp b/src/lib/Gen/hbs/Builder.cpp index 7e40f627e..0bc5b5e28 100644 --- a/src/lib/Gen/hbs/Builder.cpp +++ b/src/lib/Gen/hbs/Builder.cpp @@ -170,8 +170,10 @@ std::string Builder:: getRelPrefix(std::size_t depth) { + Config const& config = domCorpus->config; + std::string rel_prefix; - if(! depth || ! domCorpus.options.legible_names || + if(! depth || ! config->legibleNames || ! domCorpus->config->multipage) return rel_prefix; --depth; @@ -208,6 +210,7 @@ createContext( const Info& Parent = domCorpus->get(OS.Parent); props.emplace_back("relfileprefix", getRelPrefix(Parent.Namespace.size() + 1)); + props.emplace_back("config", domCorpus->config.object()); props.emplace_back("sectionref", domCorpus.names_.getQualified(OS, '-')); return dom::Object(std::move(props)); @@ -232,6 +235,7 @@ operator()(OverloadSet const& OS) createContext(OS)); } +// Define Builder::operator() for each Info type #define DEFINE(T) template Expected \ Builder::operator()(T const&) diff --git a/src/lib/Gen/hbs/Builder.hpp b/src/lib/Gen/hbs/Builder.hpp index 7d1d1e921..cd4f8fe9d 100644 --- a/src/lib/Gen/hbs/Builder.hpp +++ b/src/lib/Gen/hbs/Builder.hpp @@ -12,7 +12,6 @@ #ifndef MRDOCS_LIB_GEN_HBS_BUILDER_HPP #define MRDOCS_LIB_GEN_HBS_BUILDER_HPP -#include "Options.hpp" #include "HandlebarsCorpus.hpp" #include "lib/Support/Radix.hpp" #include @@ -25,7 +24,7 @@ namespace clang { namespace mrdocs { namespace hbs { -/** Builds reference output. +/** Builds reference output as a string for any Info type This contains all the state information for a single thread to generate output. @@ -35,24 +34,25 @@ class Builder js::Context ctx_; Handlebars hbs_; - std::string getRelPrefix(std::size_t depth); + std::string + getRelPrefix(std::size_t depth); public: HandlebarsCorpus const& domCorpus; explicit - Builder( - HandlebarsCorpus const& corpus); + Builder(HandlebarsCorpus const& corpus); - dom::Value createContext(Info const& I); - dom::Value createContext(OverloadSet const& OS); + /** Render the contents for a symbol. + */ + template + Expected + operator()(T const&); - /** Render a Handlebars template from the templates directory. + /** Render the contents for an overload set. */ Expected - callTemplate( - std::string_view name, - dom::Value const& context); + operator()(OverloadSet const&); /** Render the header for a single page. */ @@ -64,16 +64,27 @@ class Builder Expected renderSinglePageFooter(); - /** Render the contents for a symbol. +private: + /** Create a handlebars context with the symbol and helper information. + + The helper information includes all information from the + config file, plus the symbol information. + + It also includes a sectionref helper that describes + the section where the symbol is located. */ - template - Expected - operator()(T const&); + dom::Value createContext(Info const& I); - /** Render the contents for an overload set. + /// @copydoc createContext(Info const&) + dom::Value createContext(OverloadSet const& OS); + + /** Render a Handlebars template from the templates directory. */ Expected - operator()(OverloadSet const&); + callTemplate( + std::string_view name, + dom::Value const& context); + }; } // hbs diff --git a/src/lib/Gen/hbs/HandlebarsCorpus.hpp b/src/lib/Gen/hbs/HandlebarsCorpus.hpp index cb78d9c1a..482f4f15d 100644 --- a/src/lib/Gen/hbs/HandlebarsCorpus.hpp +++ b/src/lib/Gen/hbs/HandlebarsCorpus.hpp @@ -14,7 +14,6 @@ #include #include "lib/Support/LegibleNames.hpp" -#include "Options.hpp" #include #include @@ -32,9 +31,6 @@ namespace hbs { class HandlebarsCorpus : public DomCorpus { public: - /** Options for the Handlebars corpus. */ - Options options; - /** Legible names for the Handlebars corpus. */ LegibleNames names_; @@ -49,16 +45,15 @@ class HandlebarsCorpus : public DomCorpus Initializes the HandlebarsCorpus with the given corpus and options. @param corpus The base corpus. - @param opts Options for the Handlebars corpus. + @param fileExtension The file extension for the generated files. + @param toStringFn The function to convert a Javadoc node to a string. */ HandlebarsCorpus( Corpus const& corpus, - Options&& opts, std::string_view fileExtension, std::function toStringFn) : DomCorpus(corpus) - , options(std::move(opts)) - , names_(corpus, options.legible_names) + , names_(corpus, corpus.config->legibleNames) , fileExtension(fileExtension) , toStringFn(std::move(toStringFn)) { diff --git a/src/lib/Gen/hbs/HandlebarsGenerator.cpp b/src/lib/Gen/hbs/HandlebarsGenerator.cpp index 39bf4774c..3a5e5472a 100644 --- a/src/lib/Gen/hbs/HandlebarsGenerator.cpp +++ b/src/lib/Gen/hbs/HandlebarsGenerator.cpp @@ -13,7 +13,6 @@ #include "HandlebarsGenerator.hpp" #include "HandlebarsCorpus.hpp" #include "Builder.hpp" -#include "Options.hpp" #include "MultiPageVisitor.hpp" #include "SinglePageVisitor.hpp" #include @@ -43,45 +42,13 @@ createExecutors( return group; } -/** Return loaded Options from a configuration. -*/ -Options -loadOptions( - std::string_view fileExtension, - Config const& config) -{ - Options opt; - dom::Value domOpts = config.object().get("generator").get(fileExtension); - if (domOpts.get("legible-names").isBoolean()) - { - opt.legible_names = domOpts.get("legible-names").getBool(); - } - if (domOpts.get("template-dir").isString()) - { - opt.template_dir = domOpts.get("template-dir").getString(); - opt.template_dir = files::makeAbsolute( - opt.template_dir, - config->configDir); - } - else - { - opt.template_dir = files::appendPath( - config->addons, - "generator", - fileExtension); - } - return opt; -} - HandlebarsCorpus createDomCorpus( HandlebarsGenerator const& gen, Corpus const& corpus) { - auto options = loadOptions(gen.fileExtension(), corpus.config); return { corpus, - std::move(options), gen.fileExtension(), [&gen](HandlebarsCorpus const& c, doc::Node const& n) { return gen.toString(c, n); diff --git a/src/lib/Gen/hbs/HandlebarsGenerator.hpp b/src/lib/Gen/hbs/HandlebarsGenerator.hpp index 3259b785d..bea738079 100644 --- a/src/lib/Gen/hbs/HandlebarsGenerator.hpp +++ b/src/lib/Gen/hbs/HandlebarsGenerator.hpp @@ -15,7 +15,6 @@ #include #include #include -#include #include #include diff --git a/src/lib/Gen/hbs/Options.hpp b/src/lib/Gen/hbs/Options.hpp deleted file mode 100644 index a163d03a3..000000000 --- a/src/lib/Gen/hbs/Options.hpp +++ /dev/null @@ -1,53 +0,0 @@ -// -// 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) 2023 Vinnie Falco (vinnie.falco@gmail.com) -// Copyright (c) 2024 Alan de Freitas (alandefreitas@gmail.com) -// -// Official repository: https://github.com/cppalliance/mrdocs -// - -#ifndef MRDOCS_LIB_GEN_HBS_OPTIONS_HPP -#define MRDOCS_LIB_GEN_HBS_OPTIONS_HPP - -#include -#include - -namespace clang { -namespace mrdocs { - -class Corpus; - -namespace hbs { - -/** Generator-specific options. -*/ -struct Options -{ - /** True if the generator should produce legible names. - - Legible names are symbol names safe for URLs and - file names. - - When disabled, the generator produces hashes - for symbol references. - */ - bool legible_names = true; - - /** Directory with the templates used to generate the output. - - The templates are written in Handlebars. - - The default directory is `generator/` - relative to the addons directory. - */ - std::string template_dir; -}; - -} // hbs -} // mrdocs -} // clang - -#endif diff --git a/src/lib/Lib/ConfigOptions.json b/src/lib/Lib/ConfigOptions.json index af136d940..f6e4ccbca 100644 --- a/src/lib/Lib/ConfigOptions.json +++ b/src/lib/Lib/ConfigOptions.json @@ -147,6 +147,13 @@ "type": "path", "default": "/share/mrdocs/addons", "relativeto": "" + }, + { + "name": "legible-names", + "brief": "Use legible names", + "details": "Use legible names for ids in the documentation. When set to true, MrDocs uses legible names for symbols in the documentation. These are symbols that are legible but still safe for URLs. When the option is set to false, MrDocs uses a hash of the symbol ID.", + "type": "bool", + "default": true } ] },