NLdoc.Validation.Rule behaviour (NLdoc.Validation v4.0.19)

View Source

This module provides a macro for defining validation rules for NLdoc spec objects, i.e. documents and their elements. Such rules check for semantic correctness and accessibility concerns in the spec objects.

Simply use NLdoc.Validation.Rule in your module with all details about the validation rule and implement the valid?/1 function to determine whether the spec objects that this rule validates, are valid.

You may also choose to override the validates/0 and make_finding/1 functions for more granular control over the validation process.

If your validation rule requires state to be maintained during the validation process, implement an update_state/2 function to update the NLdoc.Validation.State struct with the necessary information.

Note that the application of and merging of autofixes to a document as a result of validation is currently not implemented.

Example:

defmodule NLdoc.Validation.Rules.HeadingLevelValid do
  use NLdoc.Validation.Rule,
    severity: NLdoc.Validation.Severity.error(),
    rule: "invalid-heading-level",
    ruleset: "https://html.spec.whatwg.org/",
    ruleset_version: "5",
    validates: [NLdoc.Spec.Heading]

  @impl true
  def valid?(%NLdoc.Spec.Heading{level: level}, _),
    do: level >= 1 and level <= 6
end

Summary

Types

opt()
t()

Callbacks

make_finding(resource_id)
update_state(t, object)
valid?(object, t)
validate(object, t)
validates()

Types

opt()

@type opt() ::
  {:severity, NLdoc.Validation.Severity.t()}
  | {:rule, String.t()}
  | {:ruleset, String.t()}
  | {:ruleset_version, String.t()}
  | {:validates, [module()]}

t()

@type t() :: module()

Callbacks

make_finding(resource_id)

@callback make_finding(resource_id :: String.t()) :: NLdoc.Spec.Validation.Finding.t()

update_state(t, object)

@callback update_state(NLdoc.Validation.State.t(), NLdoc.Spec.object()) ::
  NLdoc.Validation.State.t()

valid?(object, t)

@callback valid?(NLdoc.Spec.object(), NLdoc.Validation.State.t()) :: boolean()

validate(object, t)

@callback validate(NLdoc.Spec.object(), NLdoc.Validation.State.t()) ::
  NLdoc.Validation.State.t()

validates()

@callback validates() :: [module()]