Simplify Doxygen coverage (#764)

Signed-off-by: Juan Cruz Viotti <[email protected]>
sourcemeta · Feb 13, 2024 · fa016f8 · fa016f8
1 parent 05e09fc
commit fa016f8
Show file tree

Hide file tree

Showing 95 changed files with 68 additions and 1,623 deletions.
diff --git a/.github/workflows/website-build.yml b/.github/workflows/website-build.yml
@@ -15,7 +15,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v3
       - run: sudo apt update
-      - run: sudo apt-get install --yes doxygen doxygen-latex sassc
+      - run: sudo apt-get install --yes doxygen sassc
       - run: >
           cmake -S . -B ./build
           -DCMAKE_BUILD_TYPE:STRING=Release

diff --git a/.github/workflows/website-deploy.yml b/.github/workflows/website-deploy.yml
@@ -23,7 +23,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v3
       - run: sudo apt update
-      - run: sudo apt-get install --yes doxygen doxygen-latex sassc
+      - run: sudo apt-get install --yes doxygen sassc
       - run: >
           cmake -S . -B ./build
           -DCMAKE_BUILD_TYPE:STRING=Release

diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in
@@ -905,7 +905,7 @@ INPUT_ENCODING         = UTF-8
 # comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd,
 # *.vhdl, *.ucf, *.qsf and *.ice.
 
-FILE_PATTERNS          = *.h
+FILE_PATTERNS          = */include/*.h
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.

diff --git a/doxygen/todo.markdown b/doxygen/todo.markdown
@@ -8,41 +8,15 @@ missing. If you want to fund JSON BinPack's development, please consider
 Canonicalizer
 -------------
 
-These are documented and implemented in @ref canonicalizer.
+Defined in @ref compiler.
 
-| Rule                                                        | Category                                | Notes                  |
-|-------------------------------------------------------------|-----------------------------------------|------------------------|
-| @ref sourcemeta::jsonbinpack::canonicalizer::TypeUnionAnyOf | @ref canonicalizer_rules_heterogeneous  | Missing documentation  |
-| @ref sourcemeta::jsonbinpack::canonicalizer::TypeUnionAnyOf | @ref canonicalizer_rules_heterogeneous  | Resolve known bugs     |
-| SchemaBundling                                              | @ref canonicalizer_rules_simplification | Missing implementation |
-
-Encodings
----------
-
-These are declared and document in @ref encoding, and implemented in @ref
-encoder and and @ref decoder.
-
-| Encoding                                                      | Type                 | Notes                  |
-|---------------------------------------------------------------|----------------------|------------------------|
-| @ref sourcemeta::jsonbinpack::ANY_PACKED_TYPE_TAG_BYTE_PREFIX | @ref encoding_any    | Missing documentation  |
-| `ONEOF_CHOICE_INDEX_PREFIX`                                   | @ref encoding_any    | Missing implementation |
-| `BOUNDED_TYPED_LENGTH_PREFIX`                                 | @ref encoding_array  | Missing implementation |
-| `REQUIRED_ONLY_BOUNDED_TYPED_OBJECT`                          | @ref encoding_object | Missing implementation |
-| `NON_REQUIRED_BOUNDED_TYPED_OBJECT`                           | @ref encoding_object | Missing implementation |
-| `MIXED_BOUNDED_TYPED_OBJECT`                                  | @ref encoding_object | Missing implementation |
-| `REQUIRED_UNBOUNDED_TYPED_OBJECT`                             | @ref encoding_object | Missing implementation |
-| `OPTIONAL_UNBOUNDED_TYPED_OBJECT`                             | @ref encoding_object | Missing implementation |
-| `MIXED_UNBOUNDED_TYPED_OBJECT`                                | @ref encoding_object | Missing implementation |
-| `PACKED_BOUNDED_REQUIRED_OBJECT`                              | @ref encoding_object | Missing implementation |
-| `PACKED_UNBOUNDED_OBJECT`                                     | @ref encoding_object | Missing implementation |
-| `URL_PROTOCOL_HOST_REST`                                      | @ref encoding_string | Missing implementation |
-| `STRING_BROTLI`                                               | @ref encoding_string | Missing implementation |
-| `STRING_DICTIONARY_COMPRESSOR`                                | @ref encoding_string | Missing implementation |
+- `TypeUnionAnyOf`: Resolve known bugs
+- Perform JSON Schema bundling
 
 Mapper
 ------
 
-These are documented and implemented in @ref mapper.
+Defined in @ref compiler.
 
 | Category | Status                           |
 |----------|----------------------------------|
@@ -51,6 +25,27 @@ These are documented and implemented in @ref mapper.
 | Object   | Missing implementation           |
 | String   | Missing implementation           |
 
+Encodings
+---------
+
+Defined in @ref runtime.
+
+| Encoding                             | Type             | Notes                  |
+|--------------------------------------|------------------|------------------------|
+| `ONEOF_CHOICE_INDEX_PREFIX`          | @ref plan_any    | Missing implementation |
+| `BOUNDED_TYPED_LENGTH_PREFIX`        | @ref plan_array  | Missing implementation |
+| `REQUIRED_ONLY_BOUNDED_TYPED_OBJECT` | @ref plan_object | Missing implementation |
+| `NON_REQUIRED_BOUNDED_TYPED_OBJECT`  | @ref plan_object | Missing implementation |
+| `MIXED_BOUNDED_TYPED_OBJECT`         | @ref plan_object | Missing implementation |
+| `REQUIRED_UNBOUNDED_TYPED_OBJECT`    | @ref plan_object | Missing implementation |
+| `OPTIONAL_UNBOUNDED_TYPED_OBJECT`    | @ref plan_object | Missing implementation |
+| `MIXED_UNBOUNDED_TYPED_OBJECT`       | @ref plan_object | Missing implementation |
+| `PACKED_BOUNDED_REQUIRED_OBJECT`     | @ref plan_object | Missing implementation |
+| `PACKED_UNBOUNDED_OBJECT`            | @ref plan_object | Missing implementation |
+| `URL_PROTOCOL_HOST_REST`             | @ref plan_string | Missing implementation |
+| `STRING_BROTLI`                      | @ref plan_string | Missing implementation |
+| `STRING_DICTIONARY_COMPRESSOR`       | @ref plan_string | Missing implementation |
+
 JSON Schema keywords
 --------------------
 

diff --git a/src/compiler/canonicalizer.h b/src/compiler/canonicalizer.h
@@ -1,77 +1,6 @@
 #ifndef SOURCEMETA_JSONBINPACK_COMPILER_CANONICALIZER_H_
 #define SOURCEMETA_JSONBINPACK_COMPILER_CANONICALIZER_H_
 
-/// @defgroup canonicalizer Canonicalizer
-/// @brief A pure and deterministic function that simplifies a JSON Schema
-/// definition to ease the static analysis process
-///
-/// JSON Schema is a particularly expressive and complex schema language. To
-/// mitigate such complexity in the context of static analysis, the
-/// *Canonicalizer* component is a total function that maps JSON Schema
-/// definitions to equivalent but simpler JSON Schema definitions according to a
-/// set formal transformations. The concept of simplifying JSON Schema
-/// definitions based on formal transformations for static analysis purposes was
-/// originally introduced by [Type Safety with JSON
-/// Subschema](https://arxiv.org/abs/1911.12651). We extend their work by
-/// modernizing and extending their set of canonicalization rules.
-///
-/// @image html c4-jsonbinpack-canonicalizer.png width=80%
-///
-/// The canonicalizer repeatedly applies the set of defined canonizalization
-/// transformations rules to every subschema of a given JSON Schema definition
-/// until no more transformations are possible. A JSON Schema definition that
-/// cannot be further modified by any canonizalization rule is considered to be
-/// a *Canonical JSON Schema*. In order to prevent an infinite loop in the
-/// canonizalization algorithm, canonizalization rules do not conflict with each
-/// other and the pre-condition of a given canonizalization rule does not hold
-/// after such canonizalization rule has been applied to the schema.
-///
-/// Inspired by the notation introduced by [Type Safety with JSON
-/// Subschema](https://arxiv.org/abs/1911.12651), each canonizalization rule is
-/// defined using the form \f$\frac{Condition}{Transformation}\f$ where \f$S\f$
-/// corresponds to the JSON Schema in question.
-///
-/// @see mapper
-//
-/// @defgroup canonicalizer_rules_syntax_sugar Syntax Sugar
-/// @brief Syntax sugar canonicalization rules aim to simplify the
-/// keywords of JSON Schema that JSON BinPack has to deal with.
-/// A canonicalization rule is considered to be part of this category
-/// if the semantics of the schema can be expressed using simpler keywords.
-/// @ingroup canonicalizer
-///
-/// @defgroup canonicalizer_rules_superfluous Superfluous Keywords
-/// @brief Superfluous keywords canonicalization rules aim to remove
-/// keywords that are not providing any value to the given schema.
-/// A canonicalization rule is considered to be part of this category
-/// if the semantics of the schema remain the same after removing
-/// a certain keyword.
-/// @ingroup canonicalizer
-///
-/// @defgroup canonicalizer_rules_heterogeneous Heterogeneous Schemas
-/// @brief Heterogeneous schemas canonicalization rules aim to simplify
-/// schemas by ensuring that any subschema only applies to one and only
-/// one JSON data type. A canonicalization rule is considered to be part
-/// of this category if it is about turning heterogeneous schemas into
-/// homogeneous schemas.
-/// @ingroup canonicalizer
-///
-/// @defgroup canonicalizer_rules_implicit Implicit Constraints
-/// @brief Implicit constraints canonicalization rules aim to surface
-/// constraints that might apply without the schema reader realizing
-/// that this is the case. A canonicalization rule is considered to be
-/// part of this category if it is about making implicit constraints
-/// explicit.
-/// @ingroup canonicalizer
-///
-/// @defgroup canonicalizer_rules_simplification Schema Simplification
-/// @brief Schema simplification canonicalization rules aim to reduce
-/// the complexity of schemas by representing the current constraints
-/// in a different, simpler manner. A canonicalization rule is considered
-/// to be part of this category if it is about applying complex
-/// transformations for simplification purposes.
-/// @ingroup canonicalizer
-
 #include <sourcemeta/jsontoolkit/json.h>
 #include <sourcemeta/jsontoolkit/jsonschema.h>
 

diff --git a/src/compiler/canonicalizer_rules/boolean_as_enum.h b/src/compiler/canonicalizer_rules/boolean_as_enum.h
@@ -1,26 +1,8 @@
-/// @ingroup canonicalizer_rules_syntax_sugar
-///
-/// ### JSON Schema 2020-12
-///
-/// | Vocabulary URI                                         | Required |
-/// |--------------------------------------------------------|----------|
-/// | https://json-schema.org/draft/2020-12/vocab/validation | Y        |
-///
-/// According to the JSON grammar, boolean values consist of two constants:
-/// `false` and `true`. As such, setting the `type` JSON Schema keyword
-/// from the Validation vocabulary to `boolean` is equivalent to explicitly
-/// declaring the `enum` keyword from the Validation vocabulary to the
-/// constants `false` and `true`.
-///
-/// \f[\frac{S.type = boolean}{S \mapsto S \cup \{ enum \mapsto \langle false,
-/// true \rangle \} \setminus \{ type \} }\f]
-
 class BooleanAsEnum final
     : public sourcemeta::jsontoolkit::SchemaTransformRule {
 public:
   BooleanAsEnum() : SchemaTransformRule("boolean_as_enum"){};
 
-  /// The rule condition
   [[nodiscard]] auto condition(const sourcemeta::jsontoolkit::JSON &schema,
                                const std::string &dialect,
                                const std::set<std::string> &vocabularies,
@@ -35,7 +17,6 @@ class BooleanAsEnum final
            !schema.defines("enum");
   }
 
-  /// The rule transformation
   auto transform(sourcemeta::jsontoolkit::SchemaTransformer &transformer) const
       -> void override {
     auto choices = sourcemeta::jsontoolkit::JSON::make_array();

diff --git a/src/compiler/canonicalizer_rules/boolean_schema.h b/src/compiler/canonicalizer_rules/boolean_schema.h
@@ -1,28 +1,8 @@
-/// @ingroup canonicalizer_rules_syntax_sugar
-///
-/// ### JSON Schema 2020-12
-///
-/// The [Core](https://json-schema.org/draft/2020-12/json-schema-core.html)
-/// specification defines the trivial boolean schemas `true` and `false` where
-/// `true` validates successfully against any instance and `false` never
-/// validates successfully against any instance.  According to the
-/// specification, boolean schemas are syntactic sugar for the empty object
-/// schema and the `not` applicator.
-///
-/// For the `true` schema:
-///
-/// \f[\frac{S = true}{S \mapsto \{\}}\f]
-///
-/// For the `false` schema:
-///
-/// \f[\frac{S = false}{S \mapsto \{ not \mapsto \{\} \}}\f]
-
 class BooleanSchema final
     : public sourcemeta::jsontoolkit::SchemaTransformRule {
 public:
   BooleanSchema() : SchemaTransformRule("boolean_schema"){};
 
-  /// The rule condition
   [[nodiscard]] auto condition(const sourcemeta::jsontoolkit::JSON &schema,
                                const std::string &,
                                const std::set<std::string> &,
@@ -31,7 +11,6 @@ class BooleanSchema final
     return schema.is_boolean();
   }
 
-  /// The rule transformation
   auto transform(sourcemeta::jsontoolkit::SchemaTransformer &transformer) const
       -> void override {
     const bool current_value{transformer.schema().to_boolean()};

diff --git a/src/compiler/canonicalizer_rules/const_as_enum.h b/src/compiler/canonicalizer_rules/const_as_enum.h
@@ -1,24 +1,7 @@
-/// @ingroup canonicalizer_rules_syntax_sugar
-///
-/// ### JSON Schema 2020-12
-///
-/// | Vocabulary URI                                         | Required |
-/// |--------------------------------------------------------|----------|
-/// | https://json-schema.org/draft/2020-12/vocab/validation | Y        |
-///
-/// The JSON Schema Validation vocabulary defines the `enum` keyword to
-/// declare a set of matching values and the `const` keyword to define
-/// a single matching value. As such, `const` is an enumeration consisting
-/// of a single value.
-///
-/// \f[\frac{const \in dom(S)}{S \mapsto S \cup \{ enum \mapsto \langle S.const
-/// \rangle \} \setminus \{const\} }\f]
-
 class ConstAsEnum final : public sourcemeta::jsontoolkit::SchemaTransformRule {
 public:
   ConstAsEnum() : SchemaTransformRule("const_as_enum"){};
 
-  /// The rule condition
   [[nodiscard]] auto condition(const sourcemeta::jsontoolkit::JSON &schema,
                                const std::string &dialect,
                                const std::set<std::string> &vocabularies,
@@ -30,7 +13,6 @@ class ConstAsEnum final : public sourcemeta::jsontoolkit::SchemaTransformRule {
            schema.is_object() && schema.defines("const");
   }
 
-  /// The rule transformation
   auto transform(sourcemeta::jsontoolkit::SchemaTransformer &transformer) const
       -> void override {
     sourcemeta::jsontoolkit::JSON values =

diff --git a/src/compiler/canonicalizer_rules/content_schema_without_content_media_type.h b/src/compiler/canonicalizer_rules/content_schema_without_content_media_type.h
@@ -1,25 +1,9 @@
-/// @ingroup canonicalizer_rules_superfluous
-///
-/// ### JSON Schema 2020-12
-///
-/// | Vocabulary URI                                      | Required |
-/// |-----------------------------------------------------|----------|
-/// | https://json-schema.org/draft/2020-12/vocab/content | Y        |
-///
-/// The JSON Schema Content vocabulary the `contentSchema` keyword, which
-/// is set to a schema that defines the given string-encoded value. However,
-/// the `contentSchema` keyword is only considered if the `contentMediaType`
-/// keyword from the Content vocabulary is also set.
-///
-/// \f[\frac{contentSchema \in dom(S) \land contentMediaType \not\in dom(S)}{S
-/// \mapsto S \setminus \{contentSchema\} }\f]
 class ContentSchemaWithoutContentMediaType final
     : public sourcemeta::jsontoolkit::SchemaTransformRule {
 public:
   ContentSchemaWithoutContentMediaType()
       : SchemaTransformRule("content_schema_without_content_media_type"){};
 
-  /// The rule condition
   [[nodiscard]] auto condition(const sourcemeta::jsontoolkit::JSON &schema,
                                const std::string &dialect,
                                const std::set<std::string> &vocabularies,
@@ -32,7 +16,6 @@ class ContentSchemaWithoutContentMediaType final
            !schema.defines("contentMediaType");
   }
 
-  /// The rule transformation
   auto transform(sourcemeta::jsontoolkit::SchemaTransformer &transformer) const
       -> void override {
     transformer.erase("contentSchema");

diff --git a/src/compiler/canonicalizer_rules/default_metaschema_2020_12.h b/src/compiler/canonicalizer_rules/default_metaschema_2020_12.h
@@ -1,26 +1,9 @@
-/// @ingroup canonicalizer_rules_implicit
-///
-/// ### JSON Schema 2020-12
-///
-/// | Vocabulary URI                                   | Required |
-/// |--------------------------------------------------|----------|
-/// | https://json-schema.org/draft/2020-12/vocab/core | Y        |
-///
-/// If the 2020-12 draft is in use for the schema does not declare the
-/// `$schema` keyword from the Core vocabulary, then it is sensible
-/// to default to the official 2020-12 metaschema.
-///
-/// \f[\frac{\$schema \not\in dom(S)}{S
-/// \mapsto S \cup \{ \$schema \mapsto
-/// \textsl{https://json-schema.org/draft/2020-12/schema} \} }\f]
-
 class DefaultMetaschema_2020_12 final
     : public sourcemeta::jsontoolkit::SchemaTransformRule {
 public:
   DefaultMetaschema_2020_12()
       : SchemaTransformRule("default_metaschema_2020_12"){};
 
-  /// The rule condition
   [[nodiscard]] auto condition(
       const sourcemeta::jsontoolkit::JSON &schema, const std::string &dialect,
       const std::set<std::string> &vocabularies,
@@ -31,7 +14,6 @@ class DefaultMetaschema_2020_12 final
            schema.is_object() && !schema.defines("$schema") && level.empty();
   }
 
-  /// The rule transformation
   auto transform(sourcemeta::jsontoolkit::SchemaTransformer &transformer) const
       -> void override {
     transformer.assign("$schema",

diff --git a/src/compiler/canonicalizer_rules/dependent_required_tautology.h b/src/compiler/canonicalizer_rules/dependent_required_tautology.h
@@ -1,37 +1,9 @@
-/// @ingroup canonicalizer_rules_simplification
-///
-/// ### JSON Schema 2020-12
-///
-/// | Vocabulary URI                                         | Required |
-/// |--------------------------------------------------------|----------|
-/// | https://json-schema.org/draft/2020-12/vocab/validation | Y        |
-///
-/// The `required` keyword from the Validation vocabulary declares which object
-/// properties must be present in the given JSON object. The `dependentRequired`
-/// keyword from the Validation vocabulary expresses that certain properties
-/// are required based on whether other properties from the same object are
-/// required or not. Therefore, if a property is required based on the presence
-/// of another keyword that is ensured to be required, then the requirement
-/// dependency can be elevated as an unconditional requirement.
-///
-/// \f[\frac{\{ required, dependentRequired \} \subseteq S \land S.required \cap
-/// S.dependentRequired \neq \emptyset}{S \mapsto S \cup \{ dependentRequired
-/// \mapsto D, required \mapsto R \} }\f]
-///
-/// Where:
-///
-/// \f[D = \{ (k, v) \in S.dependentRequired \mid k \not\in S.required \}\f]
-///
-/// \f[R = \bigcup \{ v \mid (k, v) \in S.dependentRequired \land k \in
-/// S.required \}\f]
-
 class DependentRequiredTautology final
     : public sourcemeta::jsontoolkit::SchemaTransformRule {
 public:
   DependentRequiredTautology()
       : SchemaTransformRule("dependent_required_tautology"){};
 
-  /// The rule condition
   [[nodiscard]] auto condition(const sourcemeta::jsontoolkit::JSON &schema,
                                const std::string &dialect,
                                const std::set<std::string> &vocabularies,
@@ -52,7 +24,6 @@ class DependentRequiredTautology final
                        });
   }
 
-  /// The rule transformation
   auto transform(sourcemeta::jsontoolkit::SchemaTransformer &transformer) const
       -> void override {
     const auto &current_requirements = transformer.schema().at("required");