Merge pull request rails#47841 from p8/docs/headers-activestorage

p8 · web-flow · commit bcd19d95d8b0 · 2023-04-03T12:37:03.000+02:00
Add missing headers to Active Storage docs [ci-skip]
diff --git a/activestorage/app/models/active_storage/attachment.rb b/activestorage/app/models/active_storage/attachment.rb
@@ -2,6 +2,8 @@
 
 require "active_support/core_ext/module/delegation"
 
+# = Active Storage \Attachment
+#
 # Attachments associate records with blobs. Usually that's a one record-many blobs relationship,
 # but it is possible to associate many different records with the same blob. A foreign-key constraint
 # on the attachments table prevents blobs from being purged if they’re still attached to any records.
diff --git a/activestorage/app/models/active_storage/blob.rb b/activestorage/app/models/active_storage/blob.rb
@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# = Active Storage \Blob
+#
 # A blob is a record that contains the metadata about a file and a key for where that file resides on the service.
 # Blobs can be created in two ways:
 #
diff --git a/activestorage/app/models/active_storage/blob/analyzable.rb b/activestorage/app/models/active_storage/blob/analyzable.rb
@@ -2,6 +2,7 @@
 
 require "active_storage/analyzer/null_analyzer"
 
+# = Active Storage \Blob \Analyzable
 module ActiveStorage::Blob::Analyzable
   # Extracts and stores metadata from the file associated with this blob using a relevant analyzer. Active Storage comes
   # with built-in analyzers for images and videos. See ActiveStorage::Analyzer::ImageAnalyzer and
diff --git a/activestorage/app/models/active_storage/blob/identifiable.rb b/activestorage/app/models/active_storage/blob/identifiable.rb
@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# = Active Storage \Blob \Identifiable
 module ActiveStorage::Blob::Identifiable
   def identify
     identify_without_saving
diff --git a/activestorage/app/models/active_storage/filename.rb b/activestorage/app/models/active_storage/filename.rb
@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# = Active Storage \Filename
+#
 # Encapsulates a string representing a filename to provide convenient access to parts of it and sanitization.
 # A Filename instance is returned by ActiveStorage::Blob#filename, and is comparable so it can be used for sorting.
 class ActiveStorage::Filename
diff --git a/activestorage/app/models/active_storage/preview.rb b/activestorage/app/models/active_storage/preview.rb
@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# = Active Storage \Preview
+#
 # Some non-image blobs can be previewed: that is, they can be presented as images. A video blob can be previewed by
 # extracting its first frame, and a PDF blob can be previewed by extracting its first page.
 #
diff --git a/activestorage/app/models/active_storage/variant.rb b/activestorage/app/models/active_storage/variant.rb
@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# = Active Storage \Variant
+#
 # Image blobs can have variants that are the result of a set of transformations applied to the original.
 # These variants are used to create thumbnails, fixed-size avatars, or any other derivative image from the
 # original.
diff --git a/activestorage/app/models/active_storage/variant_with_record.rb b/activestorage/app/models/active_storage/variant_with_record.rb
@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# = Active Storage \Variant With Record
+#
 # Like an ActiveStorage::Variant, but keeps detail about the variant in the database as an
 # ActiveStorage::VariantRecord. This is only used if +ActiveStorage.track_variants+ is enabled.
 class ActiveStorage::VariantWithRecord
diff --git a/activestorage/app/models/active_storage/variation.rb b/activestorage/app/models/active_storage/variation.rb
@@ -2,6 +2,8 @@
 
 require "marcel"
 
+# = Active Storage \Variation
+#
 # A set of transformations that can be applied to a blob to create a variant. This class is exposed via
 # the ActiveStorage::Blob#variant method and should rarely be used directly.
 #
diff --git a/activestorage/lib/active_storage/analyzer.rb b/activestorage/lib/active_storage/analyzer.rb
@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module ActiveStorage
+  # = Active Storage \Analyzer
+  #
   # This is an abstract base class for analyzers, which extract metadata from blobs. See
   # ActiveStorage::Analyzer::VideoAnalyzer for an example of a concrete subclass.
   class Analyzer
diff --git a/activestorage/lib/active_storage/analyzer/audio_analyzer.rb b/activestorage/lib/active_storage/analyzer/audio_analyzer.rb
@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module ActiveStorage
+  # = Active Storage Audio \Analyzer
+  #
   # Extracts duration (seconds), bit_rate (bits/s) and sample_rate (hertz) from an audio blob.
   #
   # Example:
diff --git a/activestorage/lib/active_storage/analyzer/image_analyzer.rb b/activestorage/lib/active_storage/analyzer/image_analyzer.rb
@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module ActiveStorage
+  # = Active Storage Image \Analyzer
+  #
   # This is an abstract base class for image analyzers, which extract width and height from an image blob.
   #
   # If the image contains EXIF data indicating its angle is 90 or 270 degrees, its width and height are swapped for convenience.
diff --git a/activestorage/lib/active_storage/analyzer/video_analyzer.rb b/activestorage/lib/active_storage/analyzer/video_analyzer.rb
@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module ActiveStorage
+  # = Active Storage Video \Analyzer
+  #
   # Extracts the following from a video blob:
   #
   # * Width (pixels)
diff --git a/activestorage/lib/active_storage/attached.rb b/activestorage/lib/active_storage/attached.rb
@@ -3,6 +3,8 @@
 require "active_support/core_ext/module/delegation"
 
 module ActiveStorage
+  # = Active Storage \Attached
+  #
   # Abstract base class for the concrete ActiveStorage::Attached::One and ActiveStorage::Attached::Many
   # classes that both provide proxy access to the blob association for a record.
   class Attached
diff --git a/activestorage/lib/active_storage/attached/many.rb b/activestorage/lib/active_storage/attached/many.rb
@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module ActiveStorage
+  # = Active Storage \Attached \Many
+  #
   # Decorated proxy object representing of multiple attachments to a model.
   class Attached::Many < Attached
     ##
diff --git a/activestorage/lib/active_storage/attached/model.rb b/activestorage/lib/active_storage/attached/model.rb
@@ -3,6 +3,8 @@
 require "active_support/core_ext/object/try"
 
 module ActiveStorage
+  # = Active Storage \Attached \Model
+  #
   # Provides the class-level DSL for declaring an Active Record model's attachments.
   module Attached::Model
     extend ActiveSupport::Concern
diff --git a/activestorage/lib/active_storage/attached/one.rb b/activestorage/lib/active_storage/attached/one.rb
@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module ActiveStorage
+  # = Active Storage \Attached \One
+  #
   # Representation of a single attachment to a model.
   class Attached::One < Attached
     ##
diff --git a/activestorage/lib/active_storage/fixture_set.rb b/activestorage/lib/active_storage/fixture_set.rb
@@ -4,6 +4,8 @@
 require "active_record/secure_token"
 
 module ActiveStorage
+  # = Active Storage \FixtureSet
+  #
   # Fixtures are a way of organizing data that you want to test against; in
   # short, sample data.
   #
diff --git a/activestorage/lib/active_storage/previewer.rb b/activestorage/lib/active_storage/previewer.rb
@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module ActiveStorage
+  # = Active Storage \Previewer
+  #
   # This is an abstract base class for previewers, which generate images from blobs. See
   # ActiveStorage::Previewer::MuPDFPreviewer and ActiveStorage::Previewer::VideoPreviewer for
   # examples of concrete subclasses.
diff --git a/activestorage/lib/active_storage/service.rb b/activestorage/lib/active_storage/service.rb
@@ -6,6 +6,8 @@
 require "action_dispatch/http/content_disposition"
 
 module ActiveStorage
+  # = Active Storage \Service
+  #
   # Abstract class serving as an interface for concrete services.
   #
   # The available services are:
diff --git a/activestorage/lib/active_storage/service/azure_storage_service.rb b/activestorage/lib/active_storage/service/azure_storage_service.rb
@@ -7,6 +7,8 @@
 require "azure/storage/common/core/auth/shared_access_signature"
 
 module ActiveStorage
+  # = Active Storage \Azure Storage \Service
+  #
   # Wraps the Microsoft Azure Storage Blob Service as an Active Storage service.
   # See ActiveStorage::Service for the generic API documentation that applies to all services.
   class Service::AzureStorageService < Service
diff --git a/activestorage/lib/active_storage/service/disk_service.rb b/activestorage/lib/active_storage/service/disk_service.rb
@@ -6,6 +6,8 @@
 require "active_support/core_ext/numeric/bytes"
 
 module ActiveStorage
+  # = Active Storage \Disk \Service
+  #
   # Wraps a local disk path as an Active Storage service. See ActiveStorage::Service for the generic API
   # documentation that applies to all services.
   class Service::DiskService < Service
diff --git a/activestorage/lib/active_storage/service/gcs_service.rb b/activestorage/lib/active_storage/service/gcs_service.rb
@@ -5,6 +5,8 @@
 require "google/cloud/storage"
 
 module ActiveStorage
+  # = Active Storage \GCS \Service
+  #
   # Wraps the Google Cloud Storage as an Active Storage service. See ActiveStorage::Service for the generic API
   # documentation that applies to all services.
   class Service::GCSService < Service
diff --git a/activestorage/lib/active_storage/service/mirror_service.rb b/activestorage/lib/active_storage/service/mirror_service.rb
@@ -3,6 +3,8 @@
 require "active_support/core_ext/module/delegation"
 
 module ActiveStorage
+  # = Active Storage Mirror \Service
+  #
   # Wraps a set of mirror services and provides a single ActiveStorage::Service object that will all
   # have the files uploaded to them. A +primary+ service is designated to answer calls to:
   # * +download+
diff --git a/activestorage/lib/active_storage/service/s3_service.rb b/activestorage/lib/active_storage/service/s3_service.rb
@@ -6,6 +6,8 @@
 require "active_support/core_ext/numeric/bytes"
 
 module ActiveStorage
+  # = Active Storage \S3 \Service
+  #
   # Wraps the Amazon Simple Storage Service (S3) as an Active Storage service.
   # See ActiveStorage::Service for the generic API documentation that applies to all services.
   class Service::S3Service < Service
diff --git a/activestorage/lib/active_storage/transformers/transformer.rb b/activestorage/lib/active_storage/transformers/transformer.rb
@@ -2,6 +2,8 @@
 
 module ActiveStorage
   module Transformers
+    # = Active Storage \Transformers \Transformer
+    #
     # A Transformer applies a set of transformations to an image.
     #
     # The following concrete subclasses are included in Active Storage:

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,7 @@`
`1`	`1`	`# frozen_string_literal: true`
`2`	`2`
	`3`	`+# = Active Storage \Blob`
	`4`	`+#`
`3`	`5`	`# A blob is a record that contains the metadata about a file and a key for where that file resides on the service.`
`4`	`6`	`# Blobs can be created in two ways:`
`5`	`7`	`#`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,7 @@`
`1`	`1`	`# frozen_string_literal: true`
`2`	`2`
	`3`	`+# = Active Storage \Preview`
	`4`	`+#`
`3`	`5`	`# Some non-image blobs can be previewed: that is, they can be presented as images. A video blob can be previewed by`
`4`	`6`	`# extracting its first frame, and a PDF blob can be previewed by extracting its first page.`
`5`	`7`	`#`
Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,8 @@`
`2`	`2`
`3`	`3`	`require "marcel"`
`4`	`4`
	`5`	`+# = Active Storage \Variation`
	`6`	`+#`
`5`	`7`	`# A set of transformations that can be applied to a blob to create a variant. This class is exposed via`
`6`	`8`	`# the ActiveStorage::Blob#variant method and should rarely be used directly.`
`7`	`9`	`#`