Documentation Improvements for Spark.Dsl.Entity

[erikaaus]

Proposal

This issues is to keep track of improvement ideas for the documentation for Spark.Dsl.Entity.

Questions

• [ ] There are three undocumented functions in the module. Do we want to @doc false these functions, or write documentation for them?
• [ ] What field are required for an Entity? Do we want to specially notate that in some way?

Work to be done

• [ ] Fix inconsistent capitalization of key terms
• [ ] Write 1-2 paragraph description of what Entities are for, and how they are used.
• [ ] Add basic example of an Entity struct in moduledoc
• [ ] Add custom types for each Entity struct field. Move detailed explanation of fields and specific examples to @typedocs on these types.
  • [ ] Add typedoc - args
  • [ ] Add typedoc - auto_set_fields
  • [ ] Add typedoc - deprecations
  • [ ] Add typedoc - describe
  • [ ] Add typedoc - docs
  • [ ] Add typedoc - entities
  • [ ] Add typedoc - examples
  • [ ] Add typedoc - hide
  • [ ] Add typedoc - identifier
  • [ ] Add typedoc - imports
  • [ ] Add typedoc - links
  • [ ] Add typedoc - modules
  • [ ] Add typedoc - name
  • [ ] Add typedoc - no_depend_modules
  • [ ] Add typedoc - recursive_as
  • [ ] Add typedoc - schema (typedoc belongs in  Spark.OptionsHelper)
  • [ ] Add typedoc - singleton_entity_keys
  • [ ] Add typedoc - snippet
  • [ ] Add typedoc - target
  • [ ] Add typedoc - transform
  • [ ] Fix transform type from mfa() to {module(), function :: atom(), args :: [any()]}

[erikaaus]

Question: What are deprecations? They're typed as a keyword list of strings.

Question: What's the difference between describe and docs?

[erikaaus]

Question: What is the examples field for?

[erikaaus]

Question: What is an example of an identifier? It's mentioned in the moduledoc, but it was automatically added to the typespec by Elixir, so it's listed as term().

[zachdaniel]

Question: What are deprecations? They're typed as a keyword list of strings.

Question: What's the difference between describe and docs?

deprecations are specific keys in the schema that have been deprecated. i.e deprecations: [name: "The name option has been deprecated, use surname"] instead.

describe is your user provided documentation. docs should not be set by the user. It is an internal field.

[zachdaniel]

Question: What is the examples field for?

The examples field allows you to show examples of a given section or entity. For example:

@attribute %Spark.Dsl.Entity{
  name: :attribute,
  ...,
  examples: [
    """
    attribute :foo, :string
    """
  ]
}

It should be shown in the automatically generated documentation.

[zachdaniel]

Question: What is an example of an identifier? It's mentioned in the moduledoc, but it was automatically added to the typespec by Elixir, so it's listed as term().

identifier refers to a field on the entity that it should be unique on. For example, in Ash.Resource the attribute resource is unique on :name. The type should be {:auto, :unique_integer} to automatically generate a unique integer identifier, or an atom. The {:auto, :unique_integer} kinda sounds useless at first, but entities with an identifier set on them can be used with Spark.Dsl.Transformer.replace_entity without having to pass a replacement function, which can be useful where nothing specific identifies a given entity and you have to programatically transform them.

[erikareads]

The type should be {:auto, :unique_integer} to automatically generate a unique integer identifier, or an atom.

To be clear, is that the type set by the user in their Entity, or is it the type generated by Spark if the user opts in?

If the former, I believe the type would be @type id :: {:auto, :unique_integer} | nil to reflect the fact that a user may opt out of using the identifier?

[zachdaniel]

yes, you are correct 👍