2024-10-15 malli | Clojure Slack Archive

malli

2024-10-15T14:36:38.558439Z

Hi All, what are some options for documenting the individual items in an enum? I'd like to do something similar to these examples, which obviously do not work:

[:enum [:and {:doc "the first integer greater than zero"} 1] 2 3]
[:enum ^{:doc "the first integer greater than zero"} 1 2 3]

valtteri 2024-10-15T15:48:04.379189Z

I find it hard to get my head around this. Enums are usually self-descriptive: "these are all the possible values". What is the use-case for having the need to document the values and not the enum itself?

2024-10-15T15:52:37.431329Z

My use case is values which are short forms of longer, more descriptive names. For example:

[:enum "l" "m" "h"]

You can probably infer that this is low, medium, and high, but I would prefer to document exactly what these short strings mean.

valtteri 2024-10-15T15:53:31.172169Z

Is the documentation for the developer or for some other users of the schema / data?

2024-10-15T15:54:06.789599Z

Currently just for me

valtteri 2024-10-15T15:56:36.551759Z

In that case I would either just use the longer names in the enum, unless there's a good reason to use the abbreviations. If there's a reason, then you could have something like this

(def sizes
    {"l" "large"
     "m" "medium"
     "s" "small"})

  (def my-schema (into [:enum] (keys sizes)))

2024-10-15T15:58:21.677579Z

Thanks, I'll go with that second option and just document on the enum where to go for more info about the values.

valtteri 2024-10-15T15:58:55.197839Z

Yep, if your editor is configured correctly, you should be able to "jump to definition" directly from sizes symbol in the schema.

👍 1

juhoteperi 2024-10-15T18:08:27.255239Z

OpenAPI doesn't support docstring per enum value either. They recommend using the description field of the enum schema: https://swagger.io/docs/specification/v3_0/data-models/enums/

Clojurians Log v2

malli