feat: add support for passing TSdoc

tijmenb · tijmenb · commit a0245b3b97f0 · 2025-11-15T10:56:07.000+01:00
diff --git a/playground/vanilla/app/serializers/video_serializer.rb b/playground/vanilla/app/serializers/video_serializer.rb
@@ -5,10 +5,14 @@ class VideoSerializer < BaseSerializer
     :id,
     :created_at,
     :title,
-    :youtube_id,
+    youtube_id: {doc: "YouTube ID of the video"},
   )
 
-  type :string, optional: true
+  type :string, optional: true, doc: <<~DOC
+    A URL to the video on YouTube
+
+    @example https://www.youtube.com/watch?v=dQw4w9WgXcQ
+  DOC
   def youtube_url
     video.youtube_url
   end
diff --git a/spec/types_from_serializers/__snapshots__/interfaces_ComposerSerializer.snap b/spec/types_from_serializers/__snapshots__/interfaces_ComposerSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey b379726b6fef2dadbfd614384b868746
+// TypesFromSerializers CacheKey c5f5056c4fa3626c5c1908d0f1dcfe8d
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 
diff --git a/spec/types_from_serializers/__snapshots__/interfaces_ComposerWithSongsSerializer.snap b/spec/types_from_serializers/__snapshots__/interfaces_ComposerWithSongsSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey 9111c6d881174b0013582fa6366868db
+// TypesFromSerializers CacheKey acbbfcd258be7c495d2784be9b815e79
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 import type ComposerWithSongsSong from './ComposerWithSongs/Song'
diff --git a/spec/types_from_serializers/__snapshots__/interfaces_ComposerWithSongsSerializer__SongSerializer.snap b/spec/types_from_serializers/__snapshots__/interfaces_ComposerWithSongsSerializer__SongSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey a69c0dbcc904740e5de89181ef4b2837
+// TypesFromSerializers CacheKey b8af6beb071f45e87fe53318043f5388
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 
diff --git a/spec/types_from_serializers/__snapshots__/interfaces_ModelSerializer.snap b/spec/types_from_serializers/__snapshots__/interfaces_ModelSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey ed8ff6fbc986e6b666d559749c666dc5
+// TypesFromSerializers CacheKey 89c74246c39a38f244b708597ef3b884
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 import type AnyModel from '../AnyModel'
diff --git a/spec/types_from_serializers/__snapshots__/interfaces_Nested__AlbumSerializer.snap b/spec/types_from_serializers/__snapshots__/interfaces_Nested__AlbumSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey 58897b61d86838c60d1f12700f326896
+// TypesFromSerializers CacheKey ddc921e1e92a90ea686336285fcdb369
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 import type AnyModel from '../../AnyModel'
diff --git a/spec/types_from_serializers/__snapshots__/interfaces_SnakeComposerSerializer.snap b/spec/types_from_serializers/__snapshots__/interfaces_SnakeComposerSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey 89e5760366d01f7f21244d341e1af2d4
+// TypesFromSerializers CacheKey 03a6c67042bb201dfeeab4b021db7dd5
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 
diff --git a/spec/types_from_serializers/__snapshots__/interfaces_SongSerializer.snap b/spec/types_from_serializers/__snapshots__/interfaces_SongSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey f4f9e398dc092747d13607e2bdcb0846
+// TypesFromSerializers CacheKey c2c60f7c58d2fbafd49219bd8673dd15
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 import type Composer from './Composer'
diff --git a/spec/types_from_serializers/__snapshots__/interfaces_SongWithVideosSerializer.snap b/spec/types_from_serializers/__snapshots__/interfaces_SongWithVideosSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey c2d167325e7342eba01d0a78482d6d76
+// TypesFromSerializers CacheKey e6174fbd5fbf2c871782886b3b441101
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 import type Composer from './Composer'
diff --git a/spec/types_from_serializers/__snapshots__/interfaces_VideoSerializer.snap b/spec/types_from_serializers/__snapshots__/interfaces_VideoSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey 45d6b515fb6118eabbd39d586269cdd0
+// TypesFromSerializers CacheKey a64204bbe2fdb9ce364445e570177530
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 
@@ -7,6 +7,15 @@ export default interface Video {
   createdAt: string | Date
   title?: string
   untypedFieldExample: any
+  /**
+  * YouTube ID of the video
+  */
   youtubeId?: string
+  /**
+  * A URL to the video on YouTube
+  
+  @example https://www.youtube.com/watch?v=dQw4w9WgXcQ
+  
+  */
   youtubeUrl?: string
 }
diff --git a/spec/types_from_serializers/__snapshots__/interfaces_VideoWithSongSerializer.snap b/spec/types_from_serializers/__snapshots__/interfaces_VideoWithSongSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey 4042db0fa9ebdf8668c7c5f0ec172e6d
+// TypesFromSerializers CacheKey 1daf2e5be0ef6fdbfb88b36816534896
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 import type Song from './Song'
@@ -9,6 +9,15 @@ export default interface VideoWithSong {
   song: Song
   title?: string
   untypedFieldExample: any
+  /**
+  * YouTube ID of the video
+  */
   youtubeId?: string
+  /**
+  * A URL to the video on YouTube
+  
+  @example https://www.youtube.com/watch?v=dQw4w9WgXcQ
+  
+  */
   youtubeUrl?: string
 }
diff --git a/spec/types_from_serializers/__snapshots__/namespace_interfaces_ComposerSerializer.snap b/spec/types_from_serializers/__snapshots__/namespace_interfaces_ComposerSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey b379726b6fef2dadbfd614384b868746
+// TypesFromSerializers CacheKey c5f5056c4fa3626c5c1908d0f1dcfe8d
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 export {}
diff --git a/spec/types_from_serializers/__snapshots__/namespace_interfaces_ComposerWithSongsSerializer.snap b/spec/types_from_serializers/__snapshots__/namespace_interfaces_ComposerWithSongsSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey 9111c6d881174b0013582fa6366868db
+// TypesFromSerializers CacheKey acbbfcd258be7c495d2784be9b815e79
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 import type ComposerWithSongsSong from './ComposerWithSongs/Song'
diff --git a/spec/types_from_serializers/__snapshots__/namespace_interfaces_ComposerWithSongsSerializer__SongSerializer.snap b/spec/types_from_serializers/__snapshots__/namespace_interfaces_ComposerWithSongsSerializer__SongSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey a69c0dbcc904740e5de89181ef4b2837
+// TypesFromSerializers CacheKey b8af6beb071f45e87fe53318043f5388
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 export {}
diff --git a/spec/types_from_serializers/__snapshots__/namespace_interfaces_ModelSerializer.snap b/spec/types_from_serializers/__snapshots__/namespace_interfaces_ModelSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey ed8ff6fbc986e6b666d559749c666dc5
+// TypesFromSerializers CacheKey 89c74246c39a38f244b708597ef3b884
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 import type AnyModel from '../AnyModel'
diff --git a/spec/types_from_serializers/__snapshots__/namespace_interfaces_Nested__AlbumSerializer.snap b/spec/types_from_serializers/__snapshots__/namespace_interfaces_Nested__AlbumSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey 58897b61d86838c60d1f12700f326896
+// TypesFromSerializers CacheKey ddc921e1e92a90ea686336285fcdb369
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 import type AnyModel from '../../AnyModel'
diff --git a/spec/types_from_serializers/__snapshots__/namespace_interfaces_SnakeComposerSerializer.snap b/spec/types_from_serializers/__snapshots__/namespace_interfaces_SnakeComposerSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey 89e5760366d01f7f21244d341e1af2d4
+// TypesFromSerializers CacheKey 03a6c67042bb201dfeeab4b021db7dd5
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 export {}
diff --git a/spec/types_from_serializers/__snapshots__/namespace_interfaces_SongSerializer.snap b/spec/types_from_serializers/__snapshots__/namespace_interfaces_SongSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey f4f9e398dc092747d13607e2bdcb0846
+// TypesFromSerializers CacheKey c2c60f7c58d2fbafd49219bd8673dd15
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 import type Composer from './Composer'
diff --git a/spec/types_from_serializers/__snapshots__/namespace_interfaces_SongWithVideosSerializer.snap b/spec/types_from_serializers/__snapshots__/namespace_interfaces_SongWithVideosSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey c2d167325e7342eba01d0a78482d6d76
+// TypesFromSerializers CacheKey e6174fbd5fbf2c871782886b3b441101
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 import type Composer from './Composer'
diff --git a/spec/types_from_serializers/__snapshots__/namespace_interfaces_VideoSerializer.snap b/spec/types_from_serializers/__snapshots__/namespace_interfaces_VideoSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey 45d6b515fb6118eabbd39d586269cdd0
+// TypesFromSerializers CacheKey a64204bbe2fdb9ce364445e570177530
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 export {}
@@ -10,7 +10,16 @@ declare global {
       createdAt: string | Date
       title?: string
       untypedFieldExample: any
+      /**
+      * YouTube ID of the video
+      */
       youtubeId?: string
+      /**
+      * A URL to the video on YouTube
+      
+      @example https://www.youtube.com/watch?v=dQw4w9WgXcQ
+      
+      */
       youtubeUrl?: string
     }
   }
diff --git a/spec/types_from_serializers/__snapshots__/namespace_interfaces_VideoWithSongSerializer.snap b/spec/types_from_serializers/__snapshots__/namespace_interfaces_VideoWithSongSerializer.snap
@@ -1,4 +1,4 @@
-// TypesFromSerializers CacheKey 4042db0fa9ebdf8668c7c5f0ec172e6d
+// TypesFromSerializers CacheKey 1daf2e5be0ef6fdbfb88b36816534896
 //
 // DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.
 import type Song from './Song'
@@ -11,7 +11,16 @@ declare global {
       song: Song
       title?: string
       untypedFieldExample: any
+      /**
+      * YouTube ID of the video
+      */
       youtubeId?: string
+      /**
+      * A URL to the video on YouTube
+      
+      @example https://www.youtube.com/watch?v=dQw4w9WgXcQ
+      
+      */
       youtubeUrl?: string
     }
   }
diff --git a/types_from_serializers/lib/types_from_serializers.rb b/types_from_serializers/lib/types_from_serializers.rb
@@ -3,3 +3,5 @@
 require_relative "types_from_serializers/version"
 require_relative "types_from_serializers/dsl"
 require_relative "types_from_serializers/railtie"
+
+OjSerializers::Serializer::KNOWN_ATTRIBUTE_OPTIONS << :doc
diff --git a/types_from_serializers/lib/types_from_serializers/generator.rb b/types_from_serializers/lib/types_from_serializers/generator.rb
@@ -62,6 +62,7 @@ def ts_properties
                 Property.new(
                   name: key,
                   type: options[:serializer] || options[:type],
+                  doc: options[:doc],
                   optional: options[:optional] || options.key?(:if),
                   multi: options[:association] == :many,
                   column_name: options.fetch(:value_from),
@@ -146,7 +147,7 @@ def as_typescript
       indent = TypesFromSerializers.config.namespace ? 3 : 1
       <<~TS.gsub(/\n$/, "")
         interface #{name} {
-        #{"  " * indent}#{properties.index_by(&:name).values.map(&:as_typescript).join("\n#{"  " * indent}")}
+        #{"  " * indent}#{properties.index_by(&:name).values.map { |property| property.as_typescript(indent) }.join("\n#{"  " * indent}")}
         #{"  " * (indent - 1)}}
       TS
     end
@@ -182,6 +183,7 @@ def global_type?(type)
     :optional,
     :multi,
     :column_name,
+    :doc,
     keyword_init: true,
   ) do
     using SerializerRefinements
@@ -206,14 +208,24 @@ def infer_type_from(columns_hash, defined_enums, ts_interface)
       end
     end
 
-    def as_typescript
+    def as_typescript(indent = 1)
       type_str = if type.respond_to?(:ts_name)
         type.ts_name
       else
         type || TypesFromSerializers.config.unknown_type
       end
 
-      "#{name}#{"?" if optional}: #{type_str}#{"[]" if multi}"
+      comment = if doc
+        <<~TSDOC
+          /**
+          * #{doc}
+          */
+        TSDOC
+      else
+        ""
+      end
+
+      "#{comment}#{name}#{"?" if optional}: #{type_str}#{"[]" if multi}".lines.join("\n#{"  " * indent}")
     end
   end
 

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-// TypesFromSerializers CacheKey b379726b6fef2dadbfd614384b868746`
	`1`	`+// TypesFromSerializers CacheKey c5f5056c4fa3626c5c1908d0f1dcfe8d`
`2`	`2`	`//`
`3`	`3`	`// DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-// TypesFromSerializers CacheKey 9111c6d881174b0013582fa6366868db`
	`1`	`+// TypesFromSerializers CacheKey acbbfcd258be7c495d2784be9b815e79`
`2`	`2`	`//`
`3`	`3`	`// DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.`
`4`	`4`	`import type ComposerWithSongsSong from './ComposerWithSongs/Song'`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-// TypesFromSerializers CacheKey a69c0dbcc904740e5de89181ef4b2837`
	`1`	`+// TypesFromSerializers CacheKey b8af6beb071f45e87fe53318043f5388`
`2`	`2`	`//`
`3`	`3`	`// DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-// TypesFromSerializers CacheKey ed8ff6fbc986e6b666d559749c666dc5`
	`1`	`+// TypesFromSerializers CacheKey 89c74246c39a38f244b708597ef3b884`
`2`	`2`	`//`
`3`	`3`	`// DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.`
`4`	`4`	`import type AnyModel from '../AnyModel'`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-// TypesFromSerializers CacheKey 58897b61d86838c60d1f12700f326896`
	`1`	`+// TypesFromSerializers CacheKey ddc921e1e92a90ea686336285fcdb369`
`2`	`2`	`//`
`3`	`3`	`// DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.`
`4`	`4`	`import type AnyModel from '../../AnyModel'`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-// TypesFromSerializers CacheKey 89e5760366d01f7f21244d341e1af2d4`
	`1`	`+// TypesFromSerializers CacheKey 03a6c67042bb201dfeeab4b021db7dd5`
`2`	`2`	`//`
`3`	`3`	`// DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-// TypesFromSerializers CacheKey f4f9e398dc092747d13607e2bdcb0846`
	`1`	`+// TypesFromSerializers CacheKey c2c60f7c58d2fbafd49219bd8673dd15`
`2`	`2`	`//`
`3`	`3`	`// DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.`
`4`	`4`	`import type Composer from './Composer'`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-// TypesFromSerializers CacheKey c2d167325e7342eba01d0a78482d6d76`
	`1`	`+// TypesFromSerializers CacheKey e6174fbd5fbf2c871782886b3b441101`
`2`	`2`	`//`
`3`	`3`	`// DO NOT MODIFY: This file was automatically generated by TypesFromSerializers.`
`4`	`4`	`import type Composer from './Composer'`