Merge pull request #4280 from sanger/Y24-190-docs-for-develop

Y24-190: Docs for `develop`

.yardopts

@@ -1,4 +1,6 @@
 --asset docs/images:images
+--exclude app/controllers/api/v2/[^/]*\.rb
+--exclude app/controllers/api/v2/concerns/.*
 -
 LICENSE
 docs/*.md

app/controllers/api/v2/tag_group_adapter_types_controller.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Api
+  module V2
+    # Provides a JSON API controller for TagGroup::AdapterType
+    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    class TagGroupAdapterTypesController < JSONAPI::ResourceController
+      # By default JSONAPI::ResourceController provides most the standard
+      # behaviour, and in many cases this file may be left empty.
+    end
+  end
+end

app/controllers/api/v2/tube_rack_statuses_controller.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Api
+  module V2
+    # Provides a JSON API controller for TubeRackStatus
+    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    class TubeRackStatusesController < JSONAPI::ResourceController
+      # By default JSONAPI::ResourceController provides most the standard
+      # behaviour, and in many cases this file may be left empty.
+    end
+  end
+end

app/resources/api/v2/aliquot_resource.rb

@@ -2,11 +2,18 @@
 
 module Api
   module V2
-    # Provides a JSON API representation of aliquot
-    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    # @todo This documentation does not yet include a detailed description of what this resource represents.
+    # @todo This documentation does not yet include detailed descriptions for relationships, attributes and filters.
+    # @todo This documentation does not yet include any example usage of the API via cURL or similar.
+    #
+    # @note Access this resource via the `/api/v2/aliquots/` endpoint.
+    #
+    # Provides a JSON:API representation of {Aliquot}.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
     class AliquotResource < BaseResource
-      # immutable # comment to make the resource mutable
-
       default_includes :tag, :tag2
 
       # Associations

app/resources/api/v2/asset_audit_resource.rb

@@ -2,33 +2,42 @@
 
 module Api
   module V2
-    # Provides a JSON API representation of AssetAudit
-    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    # @todo This documentation does not yet include a detailed description of what this resource represents.
+    # @todo This documentation does not yet include detailed descriptions for relationships, attributes and filters.
+    # @todo This documentation does not yet include any example usage of the API via cURL or similar.
+    #
+    # @note Access this resource via the `/api/v2/asset_audits/` endpoint.
+    #
+    # Provides a JSON:API representation of {AssetAudit}.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
     class AssetAuditResource < BaseResource
       model_name 'AssetAudit'
 
       # @!attribute key
-      #  @return [String] the key of the asset audit.
+      #   @return [String] the key of the asset audit.
       attribute :key
 
       # @!attribute message
-      #  @return [String] the message of the asset audit.
+      #   @return [String] the message of the asset audit.
       attribute :message
 
       # @!attribute created_by
-      #  @return [String] the user who created the asset audit.
+      #   @return [String] the user who created the asset audit.
       attribute :created_by
 
       # @!attribute asset_uuid
-      #  @return [String] the uuid of the asset associated with the asset audit.
+      #   @return [String] the uuid of the asset associated with the asset audit.
       attribute :asset_uuid
 
       # @!attribute witnessed_by
-      #  @return [String] the user who witnessed the asset audit.
+      #   @return [String] the user who witnessed the asset audit.
       attribute :witnessed_by
 
       # @!attribute metadata
-      #  @return [Hash] the metadata of the asset audit.
+      #   @return [Hash] the metadata of the asset audit.
       attribute :metadata # Currently known clients (AssetAudits app) are sending null; unsure of the expected format.
 
       # Sets the Asset on the model using the UUID provided in the API create/update request.

app/resources/api/v2/asset_resource.rb

@@ -2,7 +2,17 @@
 
 module Api
   module V2
-    # AssetResource
+    # @todo This documentation does not yet include a detailed description of what this resource represents.
+    # @todo This documentation does not yet include detailed descriptions for relationships, attributes and filters.
+    # @todo This documentation does not yet include any example usage of the API via cURL or similar.
+    #
+    # @note Access this resource via the `/api/v2/assets/` endpoint.
+    #
+    # Provides a JSON:API representation of {Asset}.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
     class AssetResource < BaseResource
       attributes :uuid
 

app/resources/api/v2/base_resource.rb

@@ -2,8 +2,17 @@
 
 module Api
   module V2
-    # Provides extensions to JSONAPI::Resource as well as global behaviour
-    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    # @api V2
+    # @abstract
+    #
+    # @todo This documentation does not yet include complete descriptions of methods and what this class offers to its
+    #   sub-classes.
+    #
+    # Provides a base class for JSON:API representations of {ApplicationRecord} sub-classes.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
     class BaseResource < JSONAPI::Resource
       abstract
 

app/resources/api/v2/comment_resource.rb

@@ -2,13 +2,20 @@
 
 module Api
   module V2
-    # Provides a JSON API representation of Comment
-    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    # @todo This documentation does not yet include a detailed description of what this resource represents.
+    # @todo This documentation does not yet include detailed descriptions for relationships, attributes and filters.
+    # @todo This documentation does not yet include any example usage of the API via cURL or similar.
+    #
+    # @note Access this resource via the `/api/v2/comments/` endpoint.
+    #
+    # Provides a JSON:API representation of {Comment}.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
     class CommentResource < BaseResource
       # Constants...
 
-      # immutable # uncomment to make the resource immutable
-
       # model_name / model_hint if required
 
       # Associations:

app/resources/api/v2/custom_metadatum_collection_resource.rb

@@ -2,13 +2,20 @@
 
 module Api
   module V2
-    # Provides a JSON API representation of custom_metadatum_collection
-    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    # @todo This documentation does not yet include a detailed description of what this resource represents.
+    # @todo This documentation does not yet include detailed descriptions for relationships, attributes and filters.
+    # @todo This documentation does not yet include any example usage of the API via cURL or similar.
+    #
+    # @note Access this resource via the `/api/v2/custom_metadatum_collections/` endpoint.
+    #
+    # Provides a JSON:API representation of {CustomMetadatumCollection}.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
     class CustomMetadatumCollectionResource < BaseResource
       # Constants...
 
-      # immutable # uncomment to make the resource immutable
-
       # model_name / model_hint if required
 
       default_includes :uuid_object, :custom_metadata

app/resources/api/v2/fragment_resource.rb

@@ -2,7 +2,17 @@
 
 module Api
   module V2
-    # Fragment
+    # @todo This documentation does not yet include a detailed description of what this resource represents.
+    # @todo This documentation does not yet include detailed descriptions for relationships, attributes and filters.
+    # @todo This documentation does not yet include any example usage of the API via cURL or similar.
+    #
+    # @note Access this resource via the `/api/v2/fragments/` endpoint.
+    #
+    # Provides a JSON:API representation of {Fragment}.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
     class FragmentResource < JSONAPI::Resource
       attributes :uuid
     end

app/resources/api/v2/labware_resource.rb

@@ -2,7 +2,17 @@
 
 module Api
   module V2
-    # LabwareResource
+    # @todo This documentation does not yet include a detailed description of what this resource represents.
+    # @todo This documentation does not yet include detailed descriptions for relationships, attributes and filters.
+    # @todo This documentation does not yet include any example usage of the API via cURL or similar.
+    #
+    # @note Access this resource via the `/api/v2/labware/` endpoint.
+    #
+    # Provides a JSON:API representation of {Labware}.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
     class LabwareResource < BaseResource
       # We import most labware shared behaviour, this includes associations,
       # attributes and filters. By adding behaviour here we ensure that it

app/resources/api/v2/lane_resource.rb

@@ -2,12 +2,22 @@
 
 module Api
   module V2
-    # Provides a JSON API representation of receptacle
-    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    # @todo This documentation does not yet include a detailed description of what this resource represents.
+    # @todo This documentation does not yet include detailed descriptions for relationships, attributes and filters.
+    # @todo This documentation does not yet include any example usage of the API via cURL or similar.
+    #
+    # @note This resource is immutable: its endpoint will not accept `POST`, `PATCH`, or `DELETE` requests.
+    # @note Access this resource via the `/api/v2/lanes/` endpoint.
+    #
+    # Provides a JSON:API representation of {Lane}.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
     class LaneResource < BaseResource
       # Constants...
 
-      immutable # comment to make the resource mutable
+      immutable
 
       # Associations:
       has_many :samples

app/resources/api/v2/lot_resource.rb

@@ -2,13 +2,20 @@
 
 module Api
   module V2
-    # Provides a JSON API representation of Lot
-    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    # @todo This documentation does not yet include a detailed description of what this resource represents.
+    # @todo This documentation does not yet include detailed descriptions for relationships, attributes and filters.
+    # @todo This documentation does not yet include any example usage of the API via cURL or similar.
+    #
+    # @note Access this resource via the `/api/v2/lots/` endpoint.
+    #
+    # Provides a JSON:API representation of {Lot}.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
     class LotResource < BaseResource
       # Constants...
 
-      # immutable # uncomment to make the resource immutable
-
       # model_name / model_hint if required
 
       default_includes :uuid_object

app/resources/api/v2/lot_type_resource.rb

@@ -2,12 +2,22 @@
 
 module Api
   module V2
-    # Provides a JSON API representation of LotType
-    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    # @todo This documentation does not yet include a detailed description of what this resource represents.
+    # @todo This documentation does not yet include detailed descriptions for relationships, attributes and filters.
+    # @todo This documentation does not yet include any example usage of the API via cURL or similar.
+    #
+    # @note This resource is immutable: its endpoint will not accept `POST`, `PATCH`, or `DELETE` requests.
+    # @note Access this resource via the `/api/v2/lot_types/` endpoint.
+    #
+    # Provides a JSON:API representation of {LotType}.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
     class LotTypeResource < BaseResource
       # Constants...
 
-      immutable # comment to make the resource mutable
+      immutable
 
       # model_name / model_hint if required
 

app/resources/api/v2/order_resource.rb

@@ -2,13 +2,20 @@
 
 module Api
   module V2
-    # Provides a JSON API representation of order
-    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    # @todo This documentation does not yet include a detailed description of what this resource represents.
+    # @todo This documentation does not yet include detailed descriptions for relationships, attributes and filters.
+    # @todo This documentation does not yet include any example usage of the API via cURL or similar.
+    #
+    # @note Access this resource via the `/api/v2/orders/` endpoint.
+    #
+    # Provides a JSON:API representation of {Order}.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
     class OrderResource < BaseResource
       # Constants...
 
-      # immutable # uncomment to make the resource immutable
-
       # model_name / model_hint if required
 
       default_includes :uuid_object

app/resources/api/v2/pick_list_resource.rb

@@ -2,15 +2,22 @@
 
 module Api
   module V2
-    # Provides a JSON API representation of PickList
-    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    # @todo This documentation does not yet include a detailed description of what this resource represents.
+    # @todo This documentation does not yet include detailed descriptions for relationships, attributes and filters.
+    # @todo This documentation does not yet include any example usage of the API via cURL or similar.
+    #
+    # @note Access this resource via the `/api/v2/pick_lists/` endpoint.
+    #
+    # Provides a JSON:API representation of {PickList}.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
     class PickListResource < BaseResource
       # Constants...
       PERMITTED_PICK_ATTRIBUTES = %i[source_receptacle_id study_id project_id].freeze
       PERMITTED_LABWARE_PICK_ATTRIBUTES = %i[source_labware_id source_labware_barcode study_id project_id].freeze
 
-      # immutable # uncomment to make the resource immutable
-
       # model_name / model_hint if required
 
       # Associations