module Useless
  module Doc
    module Core

      # Documentation for an HTTP request.
      #
      # @!attribute [r] method
      #   @return [String] the request's HTTP method.
      #   @see Useless::Doc::Core::Request::Method
      #
      # @!attribute [r] description
      #   @return [String] a description of the request.
      #
      # @!attribute [r] authentication_required
      #   @return [Boolean] whether or not the user needs to authenticate in
      #     order to perform this request.
      #
      # @!attribute [r] parameters
      #   @return [Array<Request::Parameter>] possible parameters for the
      #     request.
      #   @see Useless::Doc::Core::Request::Parameter
      #
      # @!attribute [r] headers
      #   @return [Array<Header>] possible headers for the request.
      #   @see Useless::Doc::Core::Heaader
      #
      # @!attribute [r] body
      #   @return [Body] the body of the request.
      #   @see Useless::Doc::Core::Body
      #
      # @!attribute [r] responses
      #   @return [Array<Response>] possible responses to the request.
      #   @see Useless::Doc::Core::Response
      #
      class Request

        module Method
          GET     = 'GET'
          HEAD    = 'HEAD'
          POST    = 'POST'
          PUT     = 'PUT'
          PATCH   = 'PATCH'
          DELETE  = 'DELETE'
          TRACE   = 'TRACE'
          CONNECT = 'CONNECT'
        end

        attr_accessor :method, :description, :authentication_required,
          :parameters, :headers, :body, :responses

        # @param [Hash] attrs corresponds to the class's instance attributes.
        #
        def initialize(attrs = {})
          @method                   = attrs[:method]
          @description              = attrs[:description]
          @authentication_required  = attrs[:authentication_required]
          @parameters               = attrs[:parameters] || []
          @headers                  = attrs[:headers] || []
          @body                     = attrs[:body]
          @responses                = attrs[:responses] || []
        end

        # Documentation for a request parameter for an API action.
        #
        # @!attribute [r] type
        #   @return [String] either "path" if it's part of the URL path, or
        #     "query" if it's part of the query string.
        #
        # @!attribute [r] key
        #   @return [String] the key of the parameter.
        #
        # @!attribute [r] required
        #   @return [Boolean] whether or not the parameter is required. If it is
        #     required, and the attribute is omitted, the response should have a
        #     4xx code.
        #
        # @!attribute [r] default
        #   @return [String, Numeric] the value used if the parameter is omitted
        #     and is not required.
        #
        # @!attribute [r] description
        #   @return [String] a description of the parameter.
        #
        class Parameter

          module Type
            PATH = 'path'
            QUERY = 'query'
          end

          attr_reader :type, :key, :required, :default, :description

          # @param [Hash] attrs corresponds to the class's instance attributes.
          #
          def initialize(attrs = {})
            @type         = attrs[:type]
            @key          = attrs[:key]
            @required     = attrs[:required]
            @default      = attrs[:default]
            @description  = attrs[:description]
          end
        end
      end
    end
  end
end