dsv7-parser 7.0.1 → 7.0.2

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

@@ -1,17 +1,22 @@
 # frozen_string_literal: true
 
-# Date and time datatype checks.
-#
-# Enforces textual formats before validating value ranges:
-# - Datum:    TT.MM.JJJJ (validated via Date.strptime)
-# - Uhrzeit:  HH:MM      (0..23, 0..59)
-# - Zeit:     HH:MM:SS,hh (0..23, 0..59, 0..59, 0..99)
-
 require 'date'
 
 module Dsv7
   class Validator
+    ##
+    # Date and time datatype checks.
+    #
+    # Enforces textual formats before validating value ranges:
+    # - Datum:    TT.MM.JJJJ (validated via Date.strptime)
+    # - Uhrzeit:  HH:MM      (0..23, 0..59)
+    # - Zeit:     HH:MM:SS,hh (0..23, 0..59, 0..59, 0..99)
+    #
+    # @see specification/dsv7/dsv7_specification.md Date/time formats
+    # @api private
     module WkTypeChecksDateTime
+      private
+
       def check_datum(name, idx, val, line_number, _opts = nil)
         return add_error(datum_format_error(name, idx, val, line_number)) unless
           val.match?(/^\d{2}\.\d{2}\.\d{4}$/)

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

@@ -1,13 +1,18 @@
 # frozen_string_literal: true
 
-# Enum/group checks (part 1): Bahnlänge, Zeitmessung, Land, etc.
-#
-# These normalize expectations found in the spec and examples and produce
-# actionable error messages that include allowed values.
-
 module Dsv7
   class Validator
+    ##
+    # Enum/group checks (part 1): Bahnlänge, Zeitmessung, Land, etc.
+    #
+    # These normalize expectations found in the spec and examples and produce
+    # actionable error messages that include allowed values.
+    #
+    # @see specification/dsv7/dsv7_specification.md Enumerations overview
+    # @api private
     module WkTypeChecksEnums1
+      private
+
       def check_bahnl(name, idx, val, line_number, _opts = nil)
         allowed = %w[16 20 25 33 50 FW X]
         return if allowed.include?(val)

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

@@ -1,13 +1,18 @@
 # frozen_string_literal: true
 
-# Enum/group checks (part 2): Technik, Ausübung, Geschlecht, Wertungstyp,
-# JG/AK, Meldegeldtypen, Reaktionsart, Nachtragskennzeichen, u. a.
-#
-# Keep allowed lists centralized here for clarity and reuse across schemas.
-
 module Dsv7
   class Validator
+    ##
+    # Enum/group checks (part 2): Technik, Ausübung, Geschlecht, Wertungstyp,
+    # JG/AK, Meldegeldtypen, Reaktionsart, Nachtragskennzeichen, u. a.
+    #
+    # Keep allowed lists centralized here for clarity and reuse across schemas.
+    #
+    # @see specification/dsv7/dsv7_specification.md Enumerations overview
+    # @api private
     module WkTypeChecksEnums2
+      private
+
       def check_technik(name, idx, val, line_number, _opts = nil)
         return if %w[F R B S L X].include?(val)
 

data/lib/dsv7/validator/types.rb

@@ -1,11 +1,5 @@
 # frozen_string_literal: true
 
-# Aggregates type‑check mixins used by schemas.
-#
-# Each `check_<type>(name, index, value, line_number, opts)` method is
-# expected to either accept the value or call `add_error(message)` on the
-# including schema to record a validation error with context.
-
 require_relative 'types/common'
 require_relative 'types/datetime'
 require_relative 'types/enums1'
@@ -13,6 +7,14 @@ require_relative 'types/enums2'
 
 module Dsv7
   class Validator
+    ##
+    # Aggregates type‑check mixins used by schemas.
+    #
+    # Each `check_<type>(name, index, value, line_number, opts)` method is
+    # expected to either accept the value or call `add_error(message)` on the
+    # including schema to record a validation error with context.
+    #
+    # @api private
     module WkTypeChecks
       include WkTypeChecksCommon
       include WkTypeChecksDateTime

data/lib/dsv7/validator.rb

@@ -1,46 +1,43 @@
 # frozen_string_literal: true
 
-# Dsv7::Validator
-#
-# Validates DSV7 files (German Swimming Federation “Format 7”) against a
-# pragmatic subset of the official specification. The validator focuses on
-# high‑level envelope rules (FORMAT/DATEIENDE, encoding, comments, delimiters),
-# filename hints, element cardinalities, and per‑element attribute types for all
-# four supported list types (WKDL, VML, ERG, VRL).
-#
-# Intent
-# - Provide fast, streaming validation without external dependencies.
-# - Produce precise, stable error and warning messages suitable for tooling and
-#   tests (see `test/dsv7/*`).
-# - Keep responsibilities narrow: structural checks here; parsing in
-#   `Dsv7::Parser`.
-#
-# Public API
-# - `.validate(input) -> Dsv7::Validator::Result`
-#   Accepts a file path String, an IO, or a content String (streamed via
-#   StringIO). Always returns a `Result` object with `errors`, `warnings`,
-#   `list_type`, `version`, and `valid?`.
-#
-# Examples
-#   result = Dsv7::Validator.validate('2024-01-01-Example-Wk.DSV7')
-#   result.valid?        # => true/false
-#   result.errors        # => ["..."]
-#   result.warnings      # => ["..."]
-#   result.list_type     # => 'Wettkampfdefinitionsliste' (after FORMAT)
-#   result.version       # => '7'
-#
-# Writing good docs for new checks
-# - State the rule’s purpose and scope (what it enforces, and why).
-# - Describe inputs/outputs and when an error vs. warning is emitted.
-# - Keep messages actionable and stable; include line numbers where helpful.
-# - Reference spec sections or examples in commit messages or tests.
-# - Add both accept and reject tests under `test/dsv7/`.
-
 require 'stringio'
 require_relative 'validator/result'
 require_relative 'validator/core'
 
 module Dsv7
+  ##
+  # Dsv7::Validator
+  #
+  # Validates DSV7 files (German Swimming Federation “Format 7”) against a
+  # pragmatic subset of the official specification. The validator focuses on
+  # high‑level envelope rules (FORMAT/DATEIENDE, encoding, comments, delimiters),
+  # filename hints, element cardinalities, and per‑element attribute types for all
+  # four supported list types (WKDL, VML, ERG, VRL).
+  #
+  # Intent
+  # - Provide fast, streaming validation without external dependencies.
+  # - Produce precise, stable error and warning messages suitable for tooling and
+  #   tests (see `test/dsv7/*`).
+  # - Keep responsibilities narrow: structural checks here; parsing in
+  #   {Dsv7::Parser}.
+  #
+  # Semantics
+  # - Errors on UTF‑8 BOM and on invalid UTF‑8 (input is scrubbed for messages).
+  # - Warns once when CRLF line endings are detected (still valid).
+  # - When validating a file path, may add a filename pattern warning if it
+  #   does not match `JJJJ-MM-TT-Ort-Zusatz.DSV7`.
+  #
+  # @api public
+  # @since 7.0.0
+  # @example Validate a file by path
+  #   result = Dsv7::Validator.validate('2024-01-01-Example-Wk.DSV7')
+  #   result.valid?        # => true/false
+  #   result.errors        # => ["..."]
+  #   result.warnings      # => ["..."]
+  #   result.list_type     # => 'Wettkampfdefinitionsliste' (after FORMAT)
+  #   result.version       # => '7'
+  #
+  # @see Dsv7::Parser For streaming parsing helpers and event API
   # Validates overall conformity of a DSV7 file against high-level rules
   # extracted from the specification markdown under `specification/dsv7`.
   #
@@ -48,6 +45,7 @@ module Dsv7
   # knowledge of the full element schemas.
   class Validator
     # Known list types from the overview section
+    # @return [Array<String>]
     ALLOWED_LIST_TYPES = %w[
       Wettkampfdefinitionsliste
       Vereinsmeldeliste
@@ -55,10 +53,18 @@ module Dsv7
       Vereinsergebnisliste
     ].freeze
 
-    # Single public entrypoint. Accepts:
-    # - IO-like objects (respond_to?(:read)) → streamed
+    # Validate a DSV7 input.
+    #
+    # Accepts:
+    # - IO-like objects (`respond_to?(:read)`) → streamed
     # - String paths to files → streamed
     # - String content → streamed via StringIO
+    #
+    # @param input [IO, String] An IO, a file path String, or a String with file content
+    # @api public
+    # @since 7.0.0
+    # @return [Dsv7::Validator::Result] Validation result with errors/warnings and metadata
+    # @raise [ArgumentError] if an unsupported input type is provided
     def self.validate(input)
       return new.send(:validate_stream, input) if input.respond_to?(:read)
       return validate_path(input) if input.is_a?(String) && File.file?(input)
@@ -70,6 +76,7 @@ module Dsv7
     class << self
       private
 
+      # @api private
       def validate_path(path)
         File.open(path, 'rb') do |io|
           return new.send(:validate_stream, io, filename: File.basename(path))
@@ -79,6 +86,10 @@ module Dsv7
 
     private
 
+    # @api private
+    # @param io [IO]
+    # @param filename [String, nil]
+    # @return [Dsv7::Validator::Result]
     def validate_stream(io, filename: nil)
       result = Result.new
       Core.new(result, filename).call_io(io)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dsv7-parser
 version: !ruby/object:Gem::Version
-  version: 7.0.1
+  version: 7.0.2
 platform: ruby
 authors:
 - bigcurl
@@ -21,6 +21,7 @@ files:
 - ".gitignore"
 - ".rubocop.yml"
 - ".ruby-version"
+- ".yardopts"
 - AGENTS.md
 - Gemfile
 - Gemfile.lock