Configuration Documentation

[k8orade]

We're currently using ConfigMapper::ConfigStruct classes for defining our configuration data structure, and also maintain a separate 'configuration reference' yaml document for our users.

E.g. for the following code:

class State < ConfigMapper::ConfigStruct

  component :position do
    attribute :x, default: 0
    attribute :y, default: 0
  end

end

We would also write a companion config-reference.yml document containing:

position: 
  type: Object
  description: |
    The position of our object
position.x:
  type: Integer
  description: |
    x-coordinate
position.y:
  type: Integer
  description: |
    y-coordinate

It would be great if ConfigStruct elements (attributes, components and component_dicts) supported some additional documentation options, so that a config reference document could be generated.

I'm thinking this would involve adding description option to all elements and a type option for attributes, e.g.

component :position, description: "The position of our object" do
  attribute :x, default: 0, description: "x-coordinate", type: Integer
  attribute :y, default: 0, description: "y-coordinate", type: Integer
end

Then exposing a method on ConfigStruct objects (maybe #reference_yaml?) that would return a yaml object of the config-reference data above.

Happy to make a PR but would like some feedback first :)

[mdub]

Agreed; it would be great to be able to extract documentation from a ConfigStruct, rather than maintaining it separately.

I like the idea of adding description and type properties to attributes (and components).

Types are a bit of a conundrum. Currently, the closest thing we have to a "type" is support for validation/coercion blocks on attributes, e.g.

attribute :port { |arg| Integer(arg) }

It probably makes sense to deprecate that approach, and move to modelling types as objects, with both descriptions and coercion behaviour, e.g.

attribute :port, type: Integer

I reckon we could leverage dry-types here; it provides a pattern for type objects that respond to name (to provide description) and call (for validation and coercion). At the very least we could be API-compatible with dry-types.

I think the method to access documentation should just be documentation, and should return Ruby data. YAML is just a serialisation format.

MyConfigModel.documentation
#=> {
  ".postion" => {
    "description" => "The position of our object"
  },
  ".postion.x" => {
    "default" => 0,
    "description" => "x-coordinate",
    "type" => "Integer"
  },
  ".postion.y" => {
    "default" => 0,
    "description" => "y-coordinate",
    "type" => "Integer"
  }
}

[mdub]

FYI, I've started work (on master) to support type objects.

[k8orade]

👍 on the merging of type/validation/coercion and 👍 for using dry-types. Great changes so far 😄