Documenting custom type variants

Is it possible to add documentation to variants?

Specifically I am looking for a way to get webstorm/intellij to show that documentation during autocomplete of custom type variant (with F1). (Guessing webstorm supports the standard Elm module documentation format.)

1 Like

Documentation for Elm in general is done by placing a comment like
{-| your docs here
-}
directly above the thing being documented. That should work. You may also need a doc comment just below the module … exposing line like
{-| module docs
@doc YourType
-}

Thanks. Yes I know about documentation in general. Was thinking if I had missed some way of doing it specifically for variants. Documenting record type fields would also be of use in my use case. Something like this:

type Layout
    {-| A Fluid layout takes as much space as possible
    -}
    = Fluid
    {-| With a Fixed layout you can define a fixed size
    -}
    | Fixed Int

type alias Layout2 =
  {-| A Fluid layout takes as much space as possible
  -}
  { fluid : SomeLayoutType
  {-| With a Fixed layout you can define a fixed size
  -}
  , fixed : SomeLayoutType
  }

I have not seen this anywhere so guessing it is not possible. I am leaning toward using functions for each variant but something like above would make it nicer in many ways…

1 Like

I don’t believe that is possible. A work around would be to write something like

{-|
There are possible UI layouts

Fuild: A Fluid layout takes as much space as possible
Fixed: With a Fixed layout you can define a fixed size
-}
type Layout
    = Fluid
    | Fixed Int

Editors won’t know to show variant specific documentation but if the editors shows the documentation for the entire type, the user can quickly spot the relevant info for the variants.

Hmm. Web storm does not show any help for custom types it seems. VS code at least shows the type documentation when using the variants. Unfortunately it also truncates them to three lines so using Fixed above shows documentation for Fluid . :slight_smile: Oh well I will use the function approach for the thing I am doing for now…

Would be nice though to be able to document per variant/field(?)

Documenting per variant seems like too much to me. It’s hard to say given we know nearly nothing about your case but for me too specific of documentation ends up becoming noise more than helpful. This can be seen with functions with custom types. We don’t copy/paste the docs for a custom type to everywhere it’s used, we just say that the function uses the type and if the user needs to know more they can go looking for the docs on that type.

I would agree on it being too much, noisy etc when looking at the code. But looking at the use case I have where I want to help the user (with an editor that supports it) by showing what happens if they use the variant I kind of think it would be nice to have. My examples were ugly I know. But to be able to document the variants in the Type doc as suggested above seems less noisy:

{-|
There are possible UI layouts

@Variant:Fuild: A Fluid layout takes as much space as possible
@Variant:Fixed: With a Fixed layout you can define a fixed size
-}
type Layout
    = Fluid
    | Fixed Int

Well this turned into a feature request now… :slight_smile:

3 Likes

A distinct advantage of the ‘wrap each variant in a function’ approach is that it gives you more flexibility to hide variants you don’t need to expose and to add new variants without creating a breaking change in the public API. I learnt this the hard way when writing a package with hundreds of custom types each with many variants (VegaLite - elm-vegalite 3.1.1).

2 Likes

This topic was automatically closed 10 days after the last reply. New replies are no longer allowed.