[1.2.0] Add @!attribute docs for Struct.new declarations (#14)

Author: unurgunite

.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-03-23 22:08:56 UTC using RuboCop version 1.84.0.
+# on 2026-03-27 06:40:04 UTC using RuboCop version 1.84.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -32,24 +32,24 @@ Metrics/BlockNesting:
 # Offense count: 4
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 413
+  Max: 393
 
 # Offense count: 30
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/CyclomaticComplexity:
   Max: 41
 
-# Offense count: 63
+# Offense count: 65
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 105
 
 # Offense count: 6
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ModuleLength:
-  Max: 393
+  Max: 396
 
-# Offense count: 8
+# Offense count: 9
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 8
@@ -69,32 +69,47 @@ Naming/MethodParameterName:
     - 'lib/docscribe/infer/returns.rb'
     - 'lib/docscribe/inline_rewriter/doc_builder.rb'
 
-# Offense count: 4
+# Offense count: 5
 # Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
 # AllowedMethods: call
 # WaywardPredicates: nonzero?
 Naming/PredicateMethod:
   Exclude:
     - 'lib/docscribe/inline_rewriter/collector.rb'
 
-# Offense count: 58
+# Offense count: 60
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
 
-# Offense count: 128
+# Offense count: 135
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 34
 
-# Offense count: 114
+# Offense count: 121
 RSpec/MultipleExpectations:
   Max: 7
 
-# Offense count: 20
+# Offense count: 13
 # Configuration parameters: AllowedConstants.
 Style/Documentation:
-  Enabled: false
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'lib/docscribe/cli.rb'
+    - 'lib/docscribe/cli/config_builder.rb'
+    - 'lib/docscribe/cli/init.rb'
+    - 'lib/docscribe/cli/options.rb'
+    - 'lib/docscribe/config.rb'
+    - 'lib/docscribe/config/emit.rb'
+    - 'lib/docscribe/config/filtering.rb'
+    - 'lib/docscribe/config/loader.rb'
+    - 'lib/docscribe/config/rbs.rb'
+    - 'lib/docscribe/config/sorbet.rb'
+    - 'lib/docscribe/config/sorting.rb'
+    - 'lib/docscribe/config/template.rb'
+    - 'lib/docscribe/config/utils.rb'
 
 # Offense count: 3
 # This cop supports safe autocorrection (--autocorrect).

README.md

@@ -17,13 +17,15 @@ returns), and respects Ruby visibility semantics — without using YARD to parse
   Sorbet `sig`, new docs are inserted above the first `sig`.
 - Heuristic type inference for params and return values, including conditional returns in rescue branches.
 - Safe and aggressive update modes:
-    - safe mode inserts missing docs, merges existing doc-like blocks, and normalizes sortable tags
-    - aggressive mode rebuilds existing doc blocks
+    - safe mode inserts missing docs, merges existing doc-like blocks, and normalizes sortable tags;
+    - aggressive mode rebuilds existing doc blocks.
 - Ruby 3.4+ syntax supported using Prism translation (see "Parser backend" below).
 - Optional external type integrations:
-    - RBS via `--rbs` / `--sig-dir`
-    - Sorbet via inline `sig` declarations and RBI files with `--sorbet` / `--rbi-dir`
-- Optional `attr_reader`/`attr_writer`/`attr_accessor` documentation via YARD `@!attribute` (see Configuration).
+    - RBS via `--rbs` / `--sig-dir`;
+    - Sorbet via inline `sig` declarations and RBI files with `--sorbet` / `--rbi-dir`.
+- Optional `@!attribute` generation for:
+    - `attr_reader` / `attr_writer` / `attr_accessor`;
+    - `Struct.new` declarations in both constant-assigned and class-based styles.
 
 Common workflows:
 
@@ -69,7 +71,12 @@ Common workflows:
     * [API (library) usage](#api-library-usage)
     * [Configuration](#configuration)
         * [Filtering](#filtering)
-        * [Attribute macros (`attr_*`)](#attribute-macros-attr_)
+        * [`attr_*` example](#attr_-example)
+        * [`Struct.new` examples](#structnew-examples)
+            * [Constant-assigned struct](#constant-assigned-struct)
+            * [Class-based struct](#class-based-struct)
+        * [Merge behavior](#merge-behavior)
+        * [Param tag style](#param-tag-style)
         * [Create a starter config](#create-a-starter-config)
     * [CI integration](#ci-integration)
     * [Comparison to YARD's parser](#comparison-to-yards-parser)
@@ -470,7 +477,6 @@ sorbet:
 ### Inline Sorbet example
 
 ```ruby
-
 class Demo
   extend T::Sig
 
@@ -484,7 +490,6 @@ end
 Docscribe will use the Sorbet signature instead of the inferred body type:
 
 ```ruby
-
 class Demo
   extend T::Sig
 
@@ -749,51 +754,129 @@ docscribe --exclude-file '/^spec\//' lib
 > `/regex/` passed to `--include`/`--exclude` is treated as a **method-id** pattern. Use `--include-file` /
 `--exclude-file` for file regex filters.
 
-### Attribute macros (`attr_*`)
-
-Docscribe can generate YARD `@!attribute` directives above `attr_reader`, `attr_writer`, and `attr_accessor`.
-
-Enable it:
+Enable attribute-style documentation generation with:
 
 ```yaml
 emit:
   attributes: true
 ```
 
-Example:
+When enabled, Docscribe can generate YARD `@!attribute` docs for:
 
-```ruby
-class User
-  attr_reader :name
+- `attr_reader`
+- `attr_writer`
+- `attr_accessor`
+- `Struct.new` declarations
 
-  private
+### `attr_*` example
 
-  attr_accessor :token
+> [!NOTE]
+> - Attribute docs are inserted above the `attr_*` call, not above generated methods (since they don’t exist as `def`
+    nodes).
+> - If RBS is enabled, Docscribe will try to use the RBS return type of the reader method as the attribute type.
+
+```ruby
+class User
+  attr_accessor :name
 end
 ```
 
-Becomes:
+Generated docs:
 
 ```ruby
 class User
-  # @!attribute [r] name
+  # @!attribute [rw] name
   #   @return [Object]
-  attr_reader :name
+  #   @param [Object] value
+  attr_accessor :name
+end
+```
 
-  private
+### `Struct.new` examples
 
-  # @!attribute [rw] token
-  # @private
-  #   @return [Object]
-  #   @param value [Object]
-  attr_accessor :token
+Docscribe supports both common `Struct.new` declaration styles.
+
+#### Constant-assigned struct
+
+```ruby
+User = Struct.new(:name, :email, keyword_init: true)
+```
+
+Generated docs:
+
+```ruby
+# @!attribute [rw] name
+#   @return [Object]
+#   @param [Object] value
+#
+# @!attribute [rw] email
+#   @return [Object]
+#   @param [Object] value
+User = Struct.new(:name, :email, keyword_init: true)
+```
+
+#### Class-based struct
+
+```ruby
+class User < Struct.new(:name, :email, keyword_init: true)
 end
 ```
 
-> [!NOTE]
-> - Attribute docs are inserted above the `attr_*` call, not above generated methods (since they don’t exist as `def`
-    nodes).
-> - If RBS is enabled, Docscribe will try to use the RBS return type of the reader method as the attribute type.
+Generated docs:
+
+```ruby
+# @!attribute [rw] name
+#   @return [Object]
+#   @param [Object] value
+#
+# @!attribute [rw] email
+#   @return [Object]
+#   @param [Object] value
+class User < Struct.new(:name, :email, keyword_init: true)
+end
+```
+
+Docscribe preserves the original declaration style and does not rewrite one form into the other.
+
+### Merge behavior
+
+Struct member docs use the same attribute documentation pipeline as `attr_*` macros, which means they participate in the
+normal safe/aggressive rewrite flow.
+
+In safe mode, Docscribe can:
+
+- insert full `@!attribute` docs when no doc-like block exists
+- append missing struct member docs into an existing doc-like block
+
+### Param tag style
+
+Generated writer-style attribute docs respect `doc.param_tag_style`.
+
+For example, with:
+
+```yaml
+doc:
+  param_tag_style: "type_name"
+```
+
+writer params are emitted as:
+
+```ruby
+#   @param [Object] value
+```
+
+With:
+
+```yaml
+doc:
+  param_tag_style: "name_first"
+```
+
+they are emitted as:
+
+```ruby
+#   @param value [Object]
+```
 
 ### Create a starter config
 

lib/docscribe/config.rb

@@ -8,10 +8,8 @@ module Docscribe
   class Config
     # Raw config hash after deep-merging user config with defaults.
     #
-    # @return [Hash]
-    #
     # @!attribute [r] raw
-    #   @return [Object]
+    #   @return [Hash]
     attr_reader :raw
 
     # Create a configuration object from a raw config hash.

lib/docscribe/config/emit.rb

@@ -109,7 +109,7 @@ def treat_options_keyword_as_hash?
     #
     # Supported values:
     # - `"type_name"` => `@param [String] name`
-    # - `"name_first"` => `@param name [String]`
+    # - `"name_type"` => `@param name [String]`
     #
     # @return [String]
     def param_tag_style

lib/docscribe/config/template.rb

@@ -59,7 +59,7 @@ def self.default_yaml
 
           # Style for generated @param tags:
           # - type_name => @param [Type] name
-          # - name_first => @param name [Type]
+          # - name_type => @param name [Type]
           param_tag_style: "type_name"
 
           # Sort generated / merged tags in safe mode when possible.