dsv7-parser 7.0.1 → 7.0.2

data/lib/dsv7/parser.rb

@@ -1,33 +1,5 @@
 # frozen_string_literal: true
 
-# Dsv7::Parser
-#
-# Streaming parser for DSV7 lists. It yields a simple event stream so callers
-# can build their own structures without loading the whole file into memory.
-# The parser is intentionally tolerant (e.g., it scrubs invalid UTF‑8 and
-# accepts BOM) — pair it with `Dsv7::Validator` for strict conformance.
-#
-# Events
-# - `[:format, { list_type: String, version: String }, line_number]` — first
-#   effective line must be a FORMAT line.
-# - `[:element, { name: String, attrs: Array<String> }, line_number]` — for
-#   each element line between FORMAT and DATEIENDE.
-# - `[:end, nil, line_number]` — emitted after `DATEIENDE` (or EOF if missing).
-#
-# Usage
-#   Dsv7::Parser.parse(io_or_path_or_string) do |type, payload, ln|
-#     case type
-#     when :format  then # inspect payload[:list_type], payload[:version]
-#     when :element then # payload[:name], payload[:attrs]
-#     when :end     then # done
-#     end
-#   end
-#
-# Documenting new helpers
-# - Describe when a helper raises (e.g., wrong list type for a type‑specific
-#   parser) and what it yields.
-# - Note streaming/encoding behavior and that comments are stripped inline.
-
 require_relative 'parser/version'
 require_relative 'parser/engine'
 require_relative 'validator'
@@ -35,14 +7,64 @@ require_relative 'stream'
 require_relative 'lex'
 
 module Dsv7
+  ##
+  # Dsv7::Parser
+  #
+  # Streaming parser for DSV7 lists. It yields a simple event stream so callers
+  # can build their own structures without loading the whole file into memory.
+  # The parser is intentionally tolerant (e.g., it scrubs invalid UTF‑8 and
+  # accepts BOM) — pair it with {Dsv7::Validator} for strict conformance.
+  #
+  # Events
+  # - `[:format, { list_type: String, version: String }, line_number]` — first
+  #   effective line must be a FORMAT line.
+  # - `[:element, { name: String, attrs: Array<String> }, line_number]` — for
+  #   each element line between FORMAT and DATEIENDE.
+  # - `[:end, nil, line_number]` — emitted after `DATEIENDE` (or EOF if missing).
+  #
+  # @api public
+  # @since 7.0.0
+  # @example Enumerate events for any list type
+  #   Dsv7::Parser.parse(io_or_path_or_string) do |type, payload, ln|
+  #     case type
+  #     when :format  then # inspect payload[:list_type], payload[:version]
+  #     when :element then # payload[:name], payload[:attrs]
+  #     when :end     then # done
+  #     end
+  #   end
+  #
+  # Documenting new helpers
+  # - Describe when a helper raises (e.g., wrong list type for a type‑specific
+  #   parser) and what it yields.
+  # - Note streaming/encoding behavior and that comments are stripped inline.
   module Parser
+    # Error type raised by the parser when the input
+    # does not satisfy basic envelope expectations.
     class Error < StandardError; end
 
+    # @!group Parsers
+    #
     # Generic streaming parser that auto-detects the list type from the
     # first effective FORMAT line and yields events for any DSV7 list.
-    # Yields [:format|:element|:end, payload, line_number].
-    # The first event is always :format with payload
-    #   { list_type: <String>, version: <String> }.
+    #
+    # The first event is always `:format` with payload
+    # `{ list_type: <String>, version: <String> }`.
+    #
+    # @api public
+    # @since 7.0.0
+    # @overload parse(input, &block)
+    #   @param input [IO, String] An IO, a file path String, or a String with file content
+    #   @yield [type, payload, line_number] Emitted for each event
+    #   @yieldparam type [Symbol] Event type (:format, :element, :end)
+    #   @yieldparam payload [Hash, nil] Event payload
+    #   @yieldparam line_number [Integer] 1-based line number of the event
+    #   @return [void]
+    # @overload parse(input)
+    #   @param input [IO, String]
+    #   @return [Enumerator] Enumerator over `[type, payload, line_number]`
+    # @see Dsv7::Validator
+    # @raise [Dsv7::Parser::Error] when the first effective line is not FORMAT
+    # @raise [ArgumentError] if the input type is unsupported
     def self.parse(input, &block)
       enum = Enumerator.new { |y| Engine.stream_any(input, y) }
       return enum.each(&block) if block_given?
@@ -51,8 +73,23 @@ module Dsv7
     end
 
     # Streaming parser for Wettkampfdefinitionsliste (WKDL).
-    # Yields [:format|:element|:end, payload, line_number].
     # Performs inline comment stripping, tolerates BOM, and scrubs UTF-8.
+    #
+    # @api public
+    # @since 7.0.0
+    # @overload parse_wettkampfdefinitionsliste(input, &block)
+    #   @param input [IO, String]
+    #   @yield [type, payload, line_number]
+    #   @yieldparam type [Symbol] Event type (:format, :element, :end)
+    #   @yieldparam payload [Hash, nil]
+    #   @yieldparam line_number [Integer]
+    #   @return [void]
+    # @overload parse_wettkampfdefinitionsliste(input)
+    #   @param input [IO, String]
+    #   @return [Enumerator]
+    # @raise [Dsv7::Parser::Error] if the list type is not WKDL
+    # @raise [ArgumentError] if the input type is unsupported
+    # @see Dsv7::Validator
     def self.parse_wettkampfdefinitionsliste(input, &block)
       enum = Enumerator.new { |y| Engine.stream_list(input, y, 'Wettkampfdefinitionsliste') }
       return enum.each(&block) if block_given?
@@ -61,8 +98,20 @@ module Dsv7
     end
 
     # Streaming parser for Vereinsmeldeliste (VML).
-    # Same contract as parse_wettkampfdefinitionsliste, but expects
-    # FORMAT:Vereinsmeldeliste;7; as the first effective line.
+    # Same contract as {parse_wettkampfdefinitionsliste}, but expects
+    # `FORMAT:Vereinsmeldeliste;7;` as the first effective line.
+    # @api public
+    # @since 7.0.0
+    # @overload parse_vereinsmeldeliste(input, &block)
+    #   @param input [IO, String]
+    #   @yield [type, payload, line_number]
+    #   @return [void]
+    # @overload parse_vereinsmeldeliste(input)
+    #   @param input [IO, String]
+    #   @return [Enumerator]
+    # @raise [Dsv7::Parser::Error] if the list type is not VML
+    # @raise [ArgumentError] if the input type is unsupported
+    # @see Dsv7::Validator
     def self.parse_vereinsmeldeliste(input, &block)
       enum = Enumerator.new { |y| Engine.stream_list(input, y, 'Vereinsmeldeliste') }
       return enum.each(&block) if block_given?
@@ -72,7 +121,19 @@ module Dsv7
 
     # Streaming parser for Wettkampfergebnisliste (ERG).
     # Same contract as the other parse_* methods, but expects
-    # FORMAT:Wettkampfergebnisliste;7; as the first effective line.
+    # `FORMAT:Wettkampfergebnisliste;7;` as the first effective line.
+    # @api public
+    # @since 7.0.0
+    # @overload parse_wettkampfergebnisliste(input, &block)
+    #   @param input [IO, String]
+    #   @yield [type, payload, line_number]
+    #   @return [void]
+    # @overload parse_wettkampfergebnisliste(input)
+    #   @param input [IO, String]
+    #   @return [Enumerator]
+    # @raise [Dsv7::Parser::Error] if the list type is not ERG
+    # @raise [ArgumentError] if the input type is unsupported
+    # @see Dsv7::Validator
     def self.parse_wettkampfergebnisliste(input, &block)
       enum = Enumerator.new { |y| Engine.stream_list(input, y, 'Wettkampfergebnisliste') }
       return enum.each(&block) if block_given?
@@ -82,13 +143,26 @@ module Dsv7
 
     # Streaming parser for Vereinsergebnisliste (VRL).
     # Same contract as the other parse_* methods, but expects
-    # FORMAT:Vereinsergebnisliste;7; as the first effective line.
+    # `FORMAT:Vereinsergebnisliste;7;` as the first effective line.
+    # @api public
+    # @since 7.0.0
+    # @overload parse_vereinsergebnisliste(input, &block)
+    #   @param input [IO, String]
+    #   @yield [type, payload, line_number]
+    #   @return [void]
+    # @overload parse_vereinsergebnisliste(input)
+    #   @param input [IO, String]
+    #   @return [Enumerator]
+    # @raise [Dsv7::Parser::Error] if the list type is not VRL
+    # @raise [ArgumentError] if the input type is unsupported
+    # @see Dsv7::Validator
     def self.parse_vereinsergebnisliste(input, &block)
       enum = Enumerator.new { |y| Engine.stream_list(input, y, 'Vereinsergebnisliste') }
       return enum.each(&block) if block_given?
 
       enum
     end
+    # @!endgroup
     # no additional private class methods
   end
 end

data/lib/dsv7/stream.rb

@@ -1,19 +1,23 @@
 # frozen_string_literal: true
 
-# Low‑level IO helpers for streaming DSV7 content.
-#
-# Responsibilities
-# - Binary mode, BOM detection, and UTF‑8 normalization.
-# - Per‑line sanitization and CR/LF handling.
-# - Inline single‑line comment removal using the `(* ... *)` syntax.
-#
-# These helpers are shared by both the validator and the parser.
-
 module Dsv7
+  ##
+  # Low‑level IO helpers for streaming DSV7 content.
+  #
+  # Responsibilities
+  # - Binary mode, BOM detection, and UTF‑8 normalization.
+  # - Per‑line sanitization and CR/LF handling.
+  # - Inline single‑line comment removal using the `(* ... *)` syntax.
+  #
+  # These helpers are shared by both the validator and the parser.
+  #
+  # @api private
   module Stream
     module_function
 
     # Puts IO into binary mode when possible (no-op for StringIO)
+    # @param io [IO]
+    # @return [void]
     def binmode_if_possible(io)
       io.binmode
     rescue StandardError
@@ -23,6 +27,8 @@ module Dsv7
     # Reads potential UTF-8 BOM from the start of IO.
     # Returns true if a BOM was found (and consumed), false otherwise.
     # If no BOM was found, unread the peeked bytes back into the IO.
+    # @param io [IO]
+    # @return [Boolean]
     def read_bom?(io)
       head = io.read(3)
       return false if head.nil? || head.empty?
@@ -38,6 +44,9 @@ module Dsv7
     # Normalizes a raw line by trimming trailing LF/CR and forcing UTF-8.
     # If invalid encoding is detected, it scrubs replacement chars and
     # calls the optional on_invalid callback.
+    # @param raw [String]
+    # @param on_invalid [Proc,nil]
+    # @return [String]
     def sanitize_line(raw, on_invalid: nil)
       s = raw.delete_suffix("\n").delete_suffix("\r")
       s.force_encoding(Encoding::UTF_8)
@@ -48,6 +57,8 @@ module Dsv7
     end
 
     # Removes inline single-line comments in the form: (* ... *)
+    # @param line [String]
+    # @return [String]
     def strip_inline_comment(line)
       return line unless line.include?('(*') && line.include?('*)')
 
@@ -56,6 +67,12 @@ module Dsv7
 
     # Iterates sanitized lines, yielding [line, line_number].
     # Returns true if any CRLF lines were observed.
+    # @param io [IO]
+    # @param on_invalid [Proc,nil]
+    # @yield [line, line_number]
+    # @yieldparam line [String]
+    # @yieldparam line_number [Integer]
+    # @return [Boolean] whether any CRLF lines were observed
     def each_sanitized_line(io, on_invalid: nil)
       had_crlf = false
       line_number = 0

data/lib/dsv7/validator/core.rb

@@ -1,17 +1,5 @@
 # frozen_string_literal: true
 
-# Core validation pipeline
-#
-# Implements the IO/line streaming for the validator:
-# - puts IO in binary mode and detects BOM
-# - normalizes lines to UTF‑8 and tracks CRLF presence
-# - strips inline comments and delegates per‑line logic to LineAnalyzer
-# - adds a filename warning if the provided path does not match the guidance
-#
-# Notes for maintainers
-# - Keep this class side‑effect free beyond writing to `Result`.
-# - Avoid accumulating state; process line‑by‑line to preserve streaming.
-
 require_relative '../stream'
 require_relative '../lex'
 require_relative 'line_analyzer'
@@ -19,12 +7,30 @@ require_relative 'line_analyzer'
 module Dsv7
   class Validator
     # Core pipeline for validator: encoding + line parsing
+    ##
+    # Core validation pipeline.
+    #
+    # Implements the IO/line streaming for the validator:
+    # - puts IO in binary mode and detects BOM
+    # - normalizes lines to UTF‑8 and tracks CRLF presence
+    # - strips inline comments and delegates per‑line logic to LineAnalyzer
+    # - adds a filename warning if the provided path does not match the guidance
+    #
+    # Notes for maintainers
+    # - Keep this class side‑effect free beyond writing to `Result`.
+    # - Avoid accumulating state; process line‑by‑line to preserve streaming.
+    #
+    # @api private
     class Core
+      # @param result [Dsv7::Validator::Result]
+      # @param filename [String, nil]
       def initialize(result, filename)
         @result = result
         @filename = filename
       end
 
+      # @param io [IO]
+      # @return [Dsv7::Validator::Result]
       def call_io(io)
         Dsv7::Stream.binmode_if_possible(io)
         check_bom_and_rewind(io)

data/lib/dsv7/validator/line_analyzer.rb

@@ -1,12 +1,5 @@
 # frozen_string_literal: true
 
-# Streaming line analyzer
-#
-# Orchestrates validation once lines have been sanitized and comments stripped.
-# Tracks the first effective FORMAT line, enforces the final DATEIENDE, and
-# dispatches element lines to list‑specific schema/type checks and cardinality
-# tracking. All findings are written into the shared `Result` instance.
-
 require_relative '../stream'
 require_relative 'line_analyzer_common'
 require_relative 'schemas/wk_schema'
@@ -16,12 +9,22 @@ require_relative 'schemas/vrl_schema'
 
 module Dsv7
   class Validator
+    ##
+    # Streaming line analyzer.
+    #
+    # Orchestrates validation once lines have been sanitized and comments stripped.
+    # Tracks the first effective FORMAT line, enforces the final DATEIENDE, and
+    # dispatches element lines to list‑specific schema/type checks and cardinality
+    # tracking. All findings are written into the shared {Dsv7::Validator::Result} instance.
+    #
+    # @api private
     class LineAnalyzer
       include LineAnalyzerWk
       include LineAnalyzerVml
       include LineAnalyzerErg
       include LineAnalyzerVrl
 
+      # @param result [Dsv7::Validator::Result]
       def initialize(result)
         @result = result
         @effective_index = 0
@@ -31,6 +34,7 @@ module Dsv7
         init_schemas_and_counters
       end
 
+      # Initialize schemas and element counters used during streaming.
       def init_schemas_and_counters
         @wk_elements = Hash.new(0)
         @wk_schema = WkSchema.new(@result)
@@ -42,9 +46,13 @@ module Dsv7
         @vrl_schema = VrlSchema.new(@result)
       end
 
+      # Process a raw input line with its 1-based line number.
+      # @param line [String]
+      # @param line_number [Integer]
+      # @return [void]
       def process_line(line, line_number)
         check_comment_balance(line, line_number)
-        trimmed = strip_inline_comment(line)
+        trimmed = Dsv7::Stream.strip_inline_comment(line).strip
         return if trimmed.empty?
 
         @effective_index += 1
@@ -54,6 +62,8 @@ module Dsv7
         handle_content_line(trimmed, line_number)
       end
 
+      # Finalize the analysis and run post/summary checks.
+      # @return [void]
       def finish
         post_validate_positions
         validate_wk_list_elements if @result.list_type == 'Wettkampfdefinitionsliste'
@@ -64,6 +74,9 @@ module Dsv7
 
       private
 
+      # Internal helper to set up schemas and counters
+      private :init_schemas_and_counters
+
       def check_comment_balance(line, line_number)
         return unless line.include?('(*') || line.include?('*)')
 
@@ -79,10 +92,6 @@ module Dsv7
         check_format_line(trimmed, line_number)
       end
 
-      def strip_inline_comment(line)
-        Dsv7::Stream.strip_inline_comment(line).strip
-      end
-
       def check_format_line(trimmed, line_number)
         m = Dsv7::Lex.parse_format(trimmed)
         return format_error(line_number) unless m

data/lib/dsv7/validator/line_analyzer_common.rb

@@ -1,13 +1,5 @@
 # frozen_string_literal: true
 
-# List‑specific analyzer mixins
-#
-# These modules encapsulate per‑list tracking and validation methods used by
-# LineAnalyzer. Each provides three responsibilities for its list type:
-# - track_*_element: counts element occurrences for cardinality checks
-# - validate_*_list_elements: validates the observed counts at finish
-# - validate_*_line: validates a single element’s attributes via the schema
-
 require_relative '../lex'
 require_relative 'cardinality'
 
@@ -15,6 +7,19 @@ module Dsv7
   class Validator
     # Handles line-by-line structural checks for WKDL-specific logic
     module LineAnalyzerWk
+      ##
+      # List‑specific analyzer mixins.
+      #
+      # These modules encapsulate per‑list tracking and validation methods used by
+      # {Dsv7::Validator::LineAnalyzer}. Each provides three responsibilities for its list type:
+      # - track_*_element: counts element occurrences for cardinality checks
+      # - validate_*_list_elements: validates the observed counts at finish
+      # - validate_*_line: validates a single element’s attributes via the schema
+      #
+      # @api private
+
+      private
+
       def track_wk_element(trimmed)
         return unless @result.list_type == 'Wettkampfdefinitionsliste'
 
@@ -47,6 +52,10 @@ module Dsv7
 
     # Handles line-by-line structural checks for VML-specific logic
     module LineAnalyzerVml
+      # @api private
+
+      private
+
       def track_vml_element(trimmed)
         return unless @result.list_type == 'Vereinsmeldeliste'
 
@@ -79,6 +88,10 @@ module Dsv7
 
     # Handles line-by-line checks for Wettkampfergebnisliste
     module LineAnalyzerErg
+      # @api private
+
+      private
+
       def track_erg_element(trimmed)
         return unless @result.list_type == 'Wettkampfergebnisliste'
 
@@ -113,6 +126,10 @@ module Dsv7
 
     # Handles line-by-line checks for Vereinsergebnisliste
     module LineAnalyzerVrl
+      # @api private
+
+      private
+
       def track_vrl_element(trimmed)
         return unless @result.list_type == 'Vereinsergebnisliste'
 

data/lib/dsv7/validator/result.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-# Validation result container
+##
+# Validation result container.
 #
 # Collects errors and warnings during a validation run and exposes
 # `list_type`/`version` after a valid FORMAT line is seen. `valid?` is true
@@ -13,7 +14,18 @@
 module Dsv7
   class Validator
     # Result container for validation
+    #
+    # @api public
+    # @since 7.0.0
     class Result
+      # @!attribute [r] errors
+      #   @return [Array<String>] Collected human-readable error messages
+      # @!attribute [r] warnings
+      #   @return [Array<String>] Collected warnings; do not affect validity
+      # @!attribute [r] list_type
+      #   @return [String, nil] List type after parsing the FORMAT line
+      # @!attribute [r] version
+      #   @return [String, nil] Format version after parsing the FORMAT line
       attr_reader :errors, :warnings, :list_type, :version
 
       def initialize
@@ -23,19 +35,31 @@ module Dsv7
         @version = nil
       end
 
+      # Add an error message.
+      # @param message [String]
+      # @return [void]
       def add_error(message)
         @errors << message
       end
 
+      # Add a warning message.
+      # @param message [String]
+      # @return [void]
       def add_warning(message)
         @warnings << message
       end
 
+      # Set FORMAT metadata after a valid FORMAT line was observed.
+      # @param list_type [String]
+      # @param version [String]
+      # @return [void]
       def set_format(list_type, version)
         @list_type = list_type
         @version = version
       end
 
+      # Whether the validation run produced no errors.
+      # @return [Boolean]
       def valid?
         @errors.empty?
       end

data/lib/dsv7/validator/schemas/base.rb

@@ -1,29 +1,37 @@
 # frozen_string_literal: true
 
-# Base class for per‑list schemas.
-#
-# A concrete schema class defines a `SCHEMAS` Hash mapping element names to an
-# Array of attribute specs. Each attribute spec is a tuple:
-#   [type, required, opts=nil]
-# where `type` corresponds to a `check_<type>` method mixed in from the
-# type‑check modules, `required` is a boolean, and `opts` can be used by a
-# specific checker.
-#
-# Cross‑field/element rules may be implemented by overriding
-# `validate_cross_rules(name, attrs, line_number)`.
-#
-# Documentation tips when adding/adjusting schemas:
-# - Copy the attribute count and types from the spec and real‑world examples.
-# - Clearly mark intentionally deferred or ambiguous elements in commit msgs.
-# - Add both positive and negative tests for each element and datatype.
-
 module Dsv7
   class Validator
+    ##
+    # Base class for per‑list schemas.
+    #
+    # A concrete schema class defines a `SCHEMAS` Hash mapping element names to an
+    # Array of attribute specs. Each attribute spec is a tuple:
+    #   `[type, required, opts=nil]`
+    # where `type` corresponds to a `check_<type>` method mixed in from the
+    # type‑check modules, `required` is a boolean, and `opts` can be used by a
+    # specific checker.
+    #
+    # Cross‑field/element rules may be implemented by overriding
+    # `validate_cross_rules(name, attrs, line_number)`.
+    #
+    # Documentation tips when adding/adjusting schemas:
+    # - Copy the attribute count and types from the spec and real‑world examples.
+    # - Clearly mark intentionally deferred or ambiguous elements in commit msgs.
+    # - Add both positive and negative tests for each element and datatype.
+    #
+    # @see specification/dsv7/dsv7_specification.md Specification reference
+    # @api private
     class SchemaBase
       def initialize(result)
         @result = result
       end
 
+      # Validate a single element against the schema map.
+      # @param name [String]
+      # @param attrs [Array<String>]
+      # @param line_number [Integer]
+      # @return [void]
       def validate_element(name, attrs, line_number)
         schema = self.class::SCHEMAS[name]
         return unless schema
@@ -50,6 +58,7 @@ module Dsv7
         end
       end
 
+      # @return [void]
       def add_error(msg)
         @result.add_error(msg)
       end

data/lib/dsv7/validator/schemas/erg_schema.rb

@@ -8,6 +8,8 @@ module Dsv7
     # Validates Wettkampfergebnisliste attribute counts and datatypes.
     # Accepts synonymous element names found in the wild
     # (e.g., STAFFELERGEBNIS/STERGEBNIS).
+    #
+    # @api private
     class ErgSchema < SchemaBase
       include WkTypeChecks
 

data/lib/dsv7/validator/schemas/vml_schema.rb

@@ -6,6 +6,8 @@ require_relative 'base'
 module Dsv7
   class Validator
     # Validates Vereinsmeldeliste attribute counts and datatypes.
+    #
+    # @api private
     class VmlSchema < SchemaBase
       include WkTypeChecks
 

data/lib/dsv7/validator/schemas/vrl_schema.rb

@@ -8,6 +8,8 @@ module Dsv7
     # Validates Vereinsergebnisliste attribute counts and datatypes.
     # Accepts synonymous element names found in the wild
     # (e.g., STAFFELERGEBNIS/STERGEBNIS).
+    #
+    # @api private
     class VrlSchema < SchemaBase
       include WkTypeChecks
 

data/lib/dsv7/validator/schemas/wk_schema.rb

@@ -9,6 +9,8 @@ module Dsv7
     #
     # The `SCHEMAS` constant defines the exact attribute counts and types per
     # element according to the current spec interpretation.
+    #
+    # @api private
     class WkSchema < SchemaBase
       include WkTypeChecks
 
@@ -52,6 +54,8 @@ module Dsv7
         'MELDEGELD' => [[:meldegeld_typ, true], [:betrag, true], [:zahl, false]]
       }.freeze
 
+      private
+
       def validate_cross_rules(name, attrs, line_number)
         return unless name == 'MELDEGELD'
 

data/lib/dsv7/validator/types/common.rb

@@ -1,16 +1,21 @@
 # frozen_string_literal: true
 
-# Common datatype checks shared across lists.
-#
-# Implementations follow the spec’s informal definitions:
-# - ZK: arbitrary UTF‑8 string (already scrubbed by the stream layer)
-# - Zahl: integer (only digits)
-# - Betrag: monetary amount in the form `x,yy`
-# - Einzelstrecke: distance (1..25000) or 0 where permitted
-
 module Dsv7
   class Validator
+    ##
+    # Common datatype checks shared across lists.
+    #
+    # Implementations follow the spec’s informal definitions:
+    # - ZK: arbitrary UTF‑8 string (already scrubbed by the stream layer)
+    # - Zahl: integer (only digits)
+    # - Betrag: monetary amount in the form `x,yy`
+    # - Einzelstrecke: distance (1..25000) or 0 where permitted
+    #
+    # @see specification/dsv7/dsv7_specification.md Datatypes overview
+    # @api private
     module WkTypeChecksCommon
+      private
+
       def check_zk(_name, _index, _val, _line_number, _opts = nil)
         # any string (already UTF-8 scrubbed); nothing to do
       end