line-message-builder 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c49876bd79a2b1e98639a5e709a41736ebc11e8c7b5bf811ca478c52df762183
-  data.tar.gz: 65ceed1d2fbef231161bc7eb131269354875c39b202da96bb6fcd42edce4bf86
+  metadata.gz: 5da58bf9e4dc340ba666cb7074f3c43c1c1bb71db5fbd9e65229064e414720d5
+  data.tar.gz: 0aed8988bdbd8b5273eeedcff427f62f8a4be6a68a9b8935d9cf0792b0b0cdff
 SHA512:
-  metadata.gz: bf2111f3470856dc021330c2fa73e3275842596d858e636d198f3dd8dcea7bddf9a60a252e4a80eb5e6297126b0ec3afeeaf143181ef565db06af9cf558c93c6
-  data.tar.gz: e98ec6e6696268c00f599de55e6b6acb09067c2370c6fc5357f8d1ee7f74b9b6e7d2c9b59a527ae5bc806ca6c685163311648b3a78641bd028d8ba6b71dc3bf1
+  metadata.gz: 867683533deec71a69b0019bc40b6abffa81fad98cab36da0c2f6f298f2c80b50f863700b88634a7bc5c66fa62ed53781782e24654aa5f427181ccb2c9dd4929
+  data.tar.gz: 8d4e59936aa354b5a2f29d21285dd449cf033ec7b6cc7b7c19fb32b3098b84bb9317a86f2998fa4dc4a5c70e837a2f0ef9a07027fbd57be691eb3e907dc4a8c2

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.8.0"}
+{".":"0.10.0"}

data/.rubocop.yml

@@ -14,3 +14,8 @@ Style/StringLiterals:
 
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
+
+# RSpec matchers often return booleans but shouldn't be named with '?'
+Naming/PredicateMethod:
+  Exclude:
+    - 'lib/line/message/rspec/**/*'

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## [0.10.0](https://github.com/elct9620/line-message-builder/compare/v0.9.0...v0.10.0) (2026-08-18)
+
+
+### ⚠ BREAKING CHANGES
+
+* **builder:** passing an option a component does not declare now raises ValidationError instead of being ignored.
+* **flex:** Flex buttons no longer accept padding, padding_all, padding_top, padding_bottom, padding_start or padding_end. Apply padding to the surrounding box instead.
+
+### Features
+
+* **actions:** add uri action ([d5fdb26](https://github.com/elct9620/line-message-builder/commit/d5fdb261014e927c58b5ae16e29c2b46d934b758))
+* **builder:** reject options a component does not declare ([0e236b3](https://github.com/elct9620/line-message-builder/commit/0e236b35ee9a562d031c474e23dc819055fdea4d))
+* **flex:** add box appearance properties and gradient background ([809e84a](https://github.com/elct9620/line-message-builder/commit/809e84a1faf6d84c15a20964c5fd78ab43907ead))
+* **flex:** add button color and scaling, drop padding ([2ef15fd](https://github.com/elct9620/line-message-builder/commit/2ef15fd09b2a441fb2f17c938497861906570f83))
+* **flex:** add icon component ([cbd1eda](https://github.com/elct9620/line-message-builder/commit/cbd1edacbef8a377b3c7ad72059833915f1ea010))
+* **flex:** add image background_color and animated ([c7f2102](https://github.com/elct9620/line-message-builder/commit/c7f21028640a47d171823e0d047e2c228f5c9844))
+* **flex:** add separator margin and color ([073c039](https://github.com/elct9620/line-message-builder/commit/073c0391d2a1092b0c4886588123491fa260b946))
+* **flex:** add span style ([ef80a4b](https://github.com/elct9620/line-message-builder/commit/ef80a4b8236bef920cc87af7cf051dd3dff5044a))
+* **flex:** add text weight, max_lines, style, decoration and scaling ([d6a83b4](https://github.com/elct9620/line-message-builder/commit/d6a83b41415e95e69cf746d5d628d48dcefb8390))
+
+## [0.9.0](https://github.com/elct9620/line-message-builder/compare/v0.8.0...v0.9.0) (2025-06-03)
+
+
+### Features
+
+* add flex separator matcher and tests for flex message components ([0d34bc9](https://github.com/elct9620/line-message-builder/commit/0d34bc9fcfeef9d2ca519548f4a83a3de046eb33))
+* add Flex::Span message builder for LINE messaging API ([a8377e9](https://github.com/elct9620/line-message-builder/commit/a8377e93861fa286e95a69d3cb3c9897c1992044))
+* add have_line_flex_span matcher and comprehensive tests for span component ([b9072cd](https://github.com/elct9620/line-message-builder/commit/b9072cd3e4c56c9346bb3d6cf98ee11374029807))
+* add Separator builder for Flex messages ([accb2aa](https://github.com/elct9620/line-message-builder/commit/accb2aa41f9a016445f377f97e93f085734764c4))
+* add separator method to Flex::Box for adding separator elements ([4125ae1](https://github.com/elct9620/line-message-builder/commit/4125ae15fd5666431ec864121cf40d3c4fb0f56f))
+* add Span component for styled text in Flex Messages ([a458d1d](https://github.com/elct9620/line-message-builder/commit/a458d1d2473e0859bc7e1c81254888a8c8fde9a7))
+* add span method to flex box builder and remove related specs ([af8dc8f](https://github.com/elct9620/line-message-builder/commit/af8dc8f9f4b8c8a7a12c15db23a50331dfc102cb))
+* add support for spans within flex text components ([90ab15d](https://github.com/elct9620/line-message-builder/commit/90ab15df7044d15308d23ef864a69f84d71e28e7))
+
+
+### Bug Fixes
+
+* add Flex::Separator component and require it in flex.rb ([4152c10](https://github.com/elct9620/line-message-builder/commit/4152c1024a7634b526f94fa4e76a518a6ff0787c))
+* ensure matcher finds flex separator in all nested containers ([d289ea1](https://github.com/elct9620/line-message-builder/commit/d289ea178e17d4ca00b796a9f666c527982d82f6))
+* remove duplicate Separator class definition in flex separator.rb ([2c6b6d0](https://github.com/elct9620/line-message-builder/commit/2c6b6d063a2da97a0781591a697cf3034cb135f6))
+
 ## [0.8.0](https://github.com/elct9620/line-message-builder/compare/v0.7.0...v0.8.0) (2025-05-24)
 
 

data/CLAUDE.md

@@ -0,0 +1,124 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Overview
+
+This is a Ruby gem that provides a Domain Specific Language (DSL) for building LINE messaging API messages. The gem allows developers to construct complex Flex Messages, text messages, and quick replies using an intuitive Ruby syntax.
+
+## Development Commands
+
+### Testing
+- `rake spec` or `bundle exec rspec` - Run all tests
+- `bundle exec rspec spec/specific_file_spec.rb` - Run a specific test file
+- `bundle exec rspec spec/specific_file_spec.rb:123` - Run test at specific line
+
+### Code Quality
+- `rake rubocop` or `bundle exec rubocop` - Run RuboCop linter
+- `bundle exec rubocop --autocorrect` - Auto-fix RuboCop violations where possible
+- `rake` - Run both tests and RuboCop (default task)
+
+### Build and Release
+- `bundle exec rake install` - Install gem locally
+- `bundle exec rake build` - Build the gem
+- `bundle exec rake release` - Release new version (creates git tag and pushes to RubyGems)
+
+### Console
+- `bin/console` - Interactive console with the gem loaded
+
+## Architecture
+
+### Core Components
+
+**Main Builder (`lib/line/message/builder.rb`)**
+- Entry point for the DSL using `Line::Message::Builder.with`
+- Handles context binding and message collection
+- Supports both regular mode and SDK v2 mode
+
+**Base Classes**
+- `Builder::Base` - Foundation for all builder components
+- `Builder::Container` - Base for components that can contain other components
+- `Builder::Context` - Manages variable access and method delegation
+
+**Message Types**
+- `Builder::Text` - Simple text messages with quick reply support
+- `Builder::Flex` - Complex flex messages with rich layouts
+
+**Flex Components (`lib/line/message/builder/flex/`)**
+- `Bubble` - Main flex container
+- `Carousel` - Collection of bubbles
+- `Box` - Layout container (horizontal/vertical/baseline)
+- `Text` - Text component with span support
+- `Span` - Inline text styling within text components
+- `Button` - Interactive buttons
+- `Image` - Image components
+- `Separator` - Visual separators
+
+**Actions (`lib/line/message/builder/actions/`)**
+- `Message` - Send text message action
+- `Postback` - Send postback data action
+
+**Quick Replies**
+- `QuickReply` - Container for quick reply buttons
+
+**Partials**
+- `Flex::Partial` - Base class for reusable flex components
+
+### Key Patterns
+
+**DSL Design**: The gem uses Ruby's block evaluation (`instance_eval`) to create a clean DSL where methods like `text`, `box`, `button` are available directly within builder blocks.
+
+**Context Handling**: The builder accepts a context object (like Rails' `view_context`) and delegates unknown methods to it, enabling access to helpers and variables.
+
+**Validation**: Components validate their properties using the `validators/` classes to ensure LINE API compatibility.
+
+**Testing Strategy**: Uses feature-style tests that build complete messages and verify their structure, rather than unit tests of individual methods.
+
+## Coding Conventions
+
+### DSL Usage
+```ruby
+# Preferred - clean DSL syntax
+Line::Message::Builder.with do
+  flex alt_text: "Hello" do
+    bubble do
+      body do
+        text "Content"
+      end
+    end
+  end
+end
+
+# Avoid - explicit block parameters
+Line::Message::Builder.with do |builder|
+  builder.flex alt_text: "Hello" do
+    # ...
+  end
+end
+```
+
+### RSpec Testing
+- Write feature tests using the full DSL as the test subject
+- Use `subject { builder.build }` pattern
+- Prefer `it { is_expected.to ... }` over `expect(subject)...`
+- One assertion per example
+- Test message structure, not implementation details
+
+### Code Style
+- Follow standard Ruby naming conventions (snake_case, CamelCase, UPPER_SNAKE_CASE)
+- No explanatory comments - code should be self-documenting
+- Use RDoc for API documentation only
+
+## RSpec Matchers
+
+The gem provides custom RSpec matchers for testing LINE messages:
+- `have_line_text_message` - Match text messages
+- `have_line_flex_message` - Match flex messages
+- `have_line_flex_bubble` - Match flex bubbles
+- `have_line_flex_component` - Match specific flex components
+
+Include with: `require "line/message/rspec"`
+
+## LLM Integration
+
+The repository includes `llm.txt` with comprehensive DSL documentation for AI assistants. This file contains detailed examples and API references for all supported LINE message types and components.

data/CONVENTIONS.md

@@ -16,6 +16,42 @@ This gem is designed to provide DSL (Domain Specific Language) for building LINE
 
 Only use comments for RDoc documentation. Do not use comments to explain anything in the code. The code should be self-explanatory. If you find yourself needing to write a comment to explain something, consider refactoring the code instead.
 
+## DSL
+
+When using the `Line::Message::Builder` DSL, following is recommended:
+
+```ruby
+Line::Message::Builder.with do
+  flex alt_text: "Hello, World!" do
+    bubble do
+      header do
+        text "Welcome to LINE Messaging API"
+      end
+      body do
+        text "This is a sample message."
+      end
+    end
+  end
+end
+```
+
+DO NOT use `do |container|` syntax as following:
+
+```ruby
+Line::Message::Builder.with do |builder|
+  builder.flex alt_text: "Hello, World!" do
+    builder.bubble do
+      builder.header do
+        builder.text "Welcome to LINE Messaging API"
+      end
+      builder.body do
+        builder.text "This is a sample message."
+      end
+    end
+  end
+end
+```
+
 ## RSpec
 
 - Write feature tests instead of unit tests, use `Line::Message::Builder` as test subject to verify the behavior of the DSL.

data/README.md

@@ -12,7 +12,7 @@ Build LINE messages using DSL (Domain Specific Language) in Ruby.
 - Build LINE messages using DSL
 - Validation of properties
 - RSpec matchers for testing
-- LINE Bot SDK v2 support (WIP)
+- LINE Bot SDK v2 support (Experimental)
 
 ## Installation
 
@@ -42,15 +42,23 @@ You can get it from [http://aotoki.me/line-message-builder/llm.txt](http://aotok
 ### Builder
 
 ```ruby
-builder = Line::MessageBuilder::Builder.with do
-    text "Hello, world!"
+builder = Line::Message::Builder.with do
+  text "Hello, world!"
 end
 
 pp builder.build
 # => [{ type: "text", text: "Hello, world!" }]
 
 puts builder.to_json
-# => {"type":"text","text":"Hello, world!"}
+# => "[{\"type\":\"text\",\"text\":\"Hello, world!\"}]"
+```
+
+To use with [line-bot-sdk-ruby](https://github.com/line/line-bot-sdk-ruby) v2, you can set mode to `sdkv2`:
+
+```ruby
+builder = Line::Message::Builder.with(mode: :sdkv2) do
+  text "Hello, world!"
+end
 ```
 
 ### Context
@@ -59,31 +67,31 @@ The context can make `Builder` to access additional methods and variables.
 
 ```ruby
 context = OpenStruct.new(
-    name: "John Doe",
+  name: "John Doe",
 )
 
-builder = Line::MessageBuilder::Builder.with(context) do
-    text "Hello, #{name}!"
+builder = Line::Message::Builder.with(context) do
+  text "Hello, #{name}!"
 end
 
 pp builder.build
 # => [{ type: "text", text: "Hello, John Doe!" }]
 
 puts builder.to_json
-# => {"type":"text","text":"Hello, John Doe!"}
+# => "[{\"type\":\"text\",\"text\":\"Hello, John Doe!\"}]"
 ```
 
 For Rails, you can use `view_context` to make `Builder` to access Rails helpers.
 
 ```ruby
 # app/controllers/line_controller.rb
-builder = Line::MessageBuilder::Builder.with(view_context) do
-    text "Anything you want?" do
-        quick_reply do
-            message "Yes", label: "Yes", image_url: image_url("yes.png")
-            message "No", label: "No", image_url: image_url("no.png")
-        end
+builder = Line::Message::Builder.with(view_context) do
+  text "Anything you want?" do
+    quick_reply do
+      message "Yes", label: "Yes", image_url: image_url("yes.png")
+      message "No", label: "No", image_url: image_url("no.png")
     end
+  end
 end
 ```
 
@@ -92,18 +100,18 @@ If not in controller, you can create a `ActionView::Base` instance and pass it t
 ```ruby
 # app/presenters/line_presenter.rb
 context = ActionView::Base.new(
-    ActionController::Base.view_paths,
-    {},
-    ActionController::Base.new,
+  ActionController::Base.view_paths,
+  {},
+  ActionController::Base.new,
 )
 
-builder = Line::MessageBuilder::Builder.with(context) do
-    text "Anything you want?" do
-        quick_reply do
-            message "Yes", label: "Yes", image_url: image_url("yes.png")
-            message "No", label: "No", image_url: image_url("no.png")
-        end
+builder = Line::Message::Builder.with(context) do
+  text "Anything you want?" do
+    quick_reply do
+      message "Yes", label: "Yes", image_url: image_url("yes.png")
+      message "No", label: "No", image_url: image_url("no.png")
     end
+  end
 end
 ```
 
@@ -124,7 +132,7 @@ class CardPartial < Line::Message::Builder::Flex::Partial
   end
 end
 
-builder = Line::MessageBuilder::Builder.with do
+builder = Line::Message::Builder.with do
   carousel do
     3.times do |i|
       bubble do
@@ -146,7 +154,7 @@ class CardPartial < Line::Message::Builder::Flex::Partial
   end
 end
 
-builder = Line::MessageBuilder::Builder.with do
+builder = Line::Message::Builder.with do
   carousel do
     3.times do |i|
       bubble do
@@ -171,6 +179,8 @@ end
 | `have_line_flex_image`      | Match a flex message with image      |
 | `have_line_flex_button`     | Match a flex message with button     |
 | `have_line_flex_box`        | Match a flex message with box        |
+| `have_line_flex_separator`  | Match a flex message with separator  |
+| `have_line_flex_icon`       | Match a flex message with icon       |
 
 
 Add `line/message/rspec` to your `spec_helper.rb` or `rails_helper.rb`:
@@ -183,7 +193,7 @@ Include `Line::Message::RSpec::Matchers` in your RSpec configuration:
 
 ```ruby
 RSpec.configure do |config|
-    config.include Line::Message::RSpec::Matchers
+  config.include Line::Message::RSpec::Matchers
 end
 ```
 
@@ -191,10 +201,10 @@ Then the matchers are available in your specs:
 
 ```ruby
 let(:builder) do
-    Line::MessageBuilder::Builder.with do
-        text "Hello, world!"
-        text "Nice to meet you!"
-    end
+  Line::Message::Builder.with do
+    text "Hello, world!"
+    text "Nice to meet you!"
+  end
 end
 
 subject { builder.build }
@@ -207,12 +217,13 @@ The matchers can work with webmock `a_request`:
 
 ```ruby
 it "reply with message" do
-    expect(a_request(:post, "https://api.line.me/v2/bot/message/reply")
-        .with(
-            body: hash_including({
-                messages: have_line_text_message(/Hello, world!/),
-            },
-        ))).to have_been_made.once
+  expect(a_request(:post, "https://api.line.me/v2/bot/message/reply")
+    .with(
+      body: hash_including({
+        messages: have_line_text_message(/Hello, world!/),
+      })
+    )
+  ).to have_been_made.once
 end
 ```
 
@@ -251,7 +262,7 @@ end
 | -----------     | --------- |
 | Postback        | 🚧        |
 | Message         | ✅        |
-| Uri             | ❌        |
+| Uri             | ✅        |
 | Datetime        | ❌        |
 | Camera          | ❌        |
 | CameraRoll      | ❌        |
@@ -265,16 +276,23 @@ end
 | --------- | ---------     |
 | Bubble    | 🚧            |
 | Carousel  | ✅            |
-| Box       | 🚧            |
-| Button    | 🚧            |
-| Image     | 🚧            |
+| Box       | ✅            |
+| Button    | ✅            |
+| Image     | ✅            |
 | Video     | ❌            |
-| Icon      | ❌            |
+| Icon      | 🚧            |
 | Text      | 🚧            |
-| Span      | ❌            |
-| Separator | ❌            |
+| Span      | 🚧            |
+| Separator | ✅            |
 | Filler    | ❌ Deprecated |
 
+Text, Span and Icon are marked partial only because their `size` option accepts
+the `none`–`xxl` keywords and pixel values, while LINE also defines `xxs` and
+`3xl`–`5xl`. Every other property of these components is supported.
+
+Bubble is missing `direction` and a bubble-level action. Postback is missing
+`inputOption` and `fillInText`.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/claudekit.json

@@ -0,0 +1,11 @@
+{
+  "rubric": {
+    "rules": [
+      {
+        "name": "RDoc",
+        "pattern": "lib/.*\\.rb$",
+        "path": "docs/rubrics/rdoc.md"
+      }
+    ]
+  }
+}

data/docs/rubrics/rdoc.md

@@ -0,0 +1,169 @@
+# RDoc Documentation Rubric
+
+This document outlines the criteria for evaluating the quality of RDoc documentation in Ruby code. We assert at least 80% of the criteria must be met to pass.
+
+## Criteria
+
+### Proper RDoc Syntax Usage (1 point)
+
+> Enforce correct RDoc markup syntax and avoid YARD-style tags that are not compatible with RDoc
+
+```ruby
+##
+# The Base class serves as the foundation for all message builder classes
+# within the Line::Message::Builder DSL. It provides core functionality
+# for defining options, handling initialization, and delegating method calls
+# to a context object.
+#
+# == Example
+#
+#   class MyBuilder < Base
+#     option :color, default: "red"
+#   end
+#
+#   builder = MyBuilder.new
+#   puts builder.color # => "red"
+```
+
+- Use RDoc directives: `:method:`, `:call-seq:`, `:nodoc:`, `:yields:` (not YARD `@param`, `@return`, `@see` tags)
+- Use `==` for major sections (h2), `===` for subsections (h3)
+- Use `[param_name]` for parameter documentation with 2-space indented descriptions
+- Use `+code+` for method names and identifiers, `<code>:symbol</code>` for symbols and string literals
+- Reference external documentation with links: `{Link Text}[URL]`
+- Use `-` for unordered lists
+- Consult [RDoc Markup Reference](https://ruby.github.io/rdoc/RDoc/MarkupReference.html) for details
+
+### Complete Class and Module Documentation (1 point)
+
+> Every public class and module must have comprehensive documentation including purpose, usage, and cross-references
+
+```ruby
+# The Text class provides a builder for creating simple text messages
+# in the LINE Messaging API. Text messages are the most basic message type,
+# consisting of plain text content with optional quick reply buttons and
+# quote tokens for replying to specific messages.
+#
+# Text messages support:
+# - Plain text content (up to 5,000 characters)
+# - Quick reply buttons for user interaction
+# - Quote tokens to reply to specific messages in a conversation
+#
+# == Example: Basic text message
+#
+#   Line::Message::Builder.with do
+#     text "Hello, world!"
+#   end
+#
+# See also:
+# - QuickReply
+# - https://developers.line.biz/en/reference/messaging-api/#text-message
+class Text < Base
+```
+
+- Classes must have a purpose statement (what it represents/does)
+- Include feature list using bullet points for complex components
+- Provide at least one complete usage example with proper context
+- Include "See also:" section with related classes and external API documentation links
+- For mixin modules, document what functionality they add to including classes
+
+### Method Documentation with Parameters and Returns (1 point)
+
+> All public methods must document their purpose, parameters, and return values clearly
+
+```ruby
+# Defines a new option for the builder class.
+#
+# This method dynamically creates an instance method on the builder class
+# with the given name. When this instance method is called without arguments,
+# it returns the current value; with an argument, it sets the value.
+#
+# [name]
+#   The name of the option to define. This will also be the name of the
+#   generated instance method.
+# [default]
+#   The default value for the option if not explicitly set.
+# [validator]
+#   An optional validator object that must respond to +valid!+ method.
+#   If the value is invalid, the validator should raise an error.
+#
+# [return]
+#   The dynamically created method name as a symbol
+#
+# == Example
+#
+#   class MyBuilder < Base
+#     option :color, default: "red"
+#     option :size, validator: SizeValidator.new
+#   end
+def option(name, default: nil, validator: nil)
+```
+
+- Document method purpose in the first paragraph
+- Use `[param_name]` format for each parameter with 2-space indented description
+- Document optional parameters and their default values
+- Include `[block]` documentation if the method accepts a block
+- Use `[return]` label to describe return value for non-obvious returns
+- Use `:nodoc:` directive for private methods and internal implementations
+
+### Dynamic Method Documentation with :method: Directive (1 point)
+
+> Dynamically defined methods must be documented using RDoc's :method: and :call-seq: directives
+
+```ruby
+# :method: quote_token
+# :call-seq:
+#   quote_token() -> String or nil
+#   quote_token(value) -> String
+#
+# Sets or gets the quote token for replying to a specific message.
+#
+# Quote tokens allow your bot to quote and reply to a specific message
+# in the conversation. When set, the original message being replied to
+# will be displayed above the new message.
+#
+# [value]
+#   The quote token string obtained from a webhook event
+option :quote_token, default: nil
+```
+
+- Use `:method:` directive to document dynamically defined methods (e.g., from `option`, `attr_accessor`)
+- Use `:call-seq:` to show both getter and setter signatures
+- Show return types using arrow notation: `method_name() -> Type or nil`
+- Document both forms: getter (no arguments) and setter (with argument)
+- Place directive immediately before the line that defines the method
+- Include parameter documentation using `[param_name]` format
+
+### Progressive Examples with Real-World Usage (1 point)
+
+> Documentation must include runnable examples that progress from simple to complex use cases
+
+```ruby
+# == Example: Basic text message
+#
+#   Line::Message::Builder.with do
+#     text "Hello, world!"
+#   end
+#
+# === Example: Text with quick reply
+#
+#   Line::Message::Builder.with do
+#     text "Choose an option:" do
+#       quick_reply do
+#         button action: :message, label: "Yes", text: "I agree"
+#         button action: :message, label: "No", text: "I disagree"
+#       end
+#     end
+#   end
+```
+
+- Provide at least one complete, executable example for public classes
+- Use descriptive example headings: `== Example: Description`
+- Show full DSL context (e.g., `Line::Message::Builder.with do ... end`)
+- Use `===` for sub-examples or variations
+- Include output comments using `# =>` notation where helpful
+- Progress from simple to complex examples
+- Indent code blocks with 2 spaces
+
+## Scoring
+
+Each criterion is worth 1 point and is awarded only when fully satisfied. A score below 80% (4 out of 5 points) indicates insufficient documentation quality.