Is it possible to document dictionary schema?

[TimeTravelPenguin]

I am curious if it is possible to make documentation showing the "types" of a dictionary variable.

Consider the following two cases:

1. I have a variable in my package:

   #let themes = (
      light: "light",
      dark: "dark"
   )

2. I have a function that returns a dictionary of entries. This might look like:

   #let return-value = (
     name: "Mocha",
     emoji: "🌿",
     order: 3,
     dark: true,
     light: false,
     colors: (
       rosewater: (
         name: "Rosewater",
         order: 0,
         hex: "#f5e0dc",
         rgb: rgb(245, 224, 220),
         accent: true,
       ),
       flamingo: (...),
       pink: (...),
       ...
     ),
   )

In my documentation, I want to have a result that looks something like:

1. This

   theme = (
       light: string,
       dark: string,
   )

2. Or this

   return-value = (
     name: string,
     emoji: string,
     order: integer,
     dark: boolean,
     light: boolean,
     colors: dict(
       key: (
         name: string,
         order: integer,
         hex: string,
         rgb: color,
         accent: boolean,
       )
     ),
   )

The second case is a bit more difficult since it has a nested schema. I was originally going to do this manually, but using - name (type): desc notation expects it to be documentation related to arguments, rather than just general text.

Edit:

For additional demonstration, this is how I am currently doing things:

/// Get the color palette for the given theme.
/// ==== Schema
/// - name (```typ string```): The name of the flavor (e.g. Frappé)
/// - emoji (```typ string```): The emoji associated with the flavor.
/// - order (```typ integer```): The order of the flavor in the Catppuccin lineup.
/// - dark (```typ boolean```): Whether the flavor is a dark theme.
/// - light (```typ boolean```): Whether the flavor is a light theme.
/// - colors (```typ dictionary```): A dictionary of colors used in the flavor. Keys are the color names as a ```typ string``` and values are dictionaries with the following keys:
///   - name (```typ string```): The name of the color.
///   - order (```typ integer```): The order of the color in the palette.
///   - hex (```typ string```): The hex value of the color.
///   - rgb (```typ string```): The RGB value of the color.
///   - accent (```typ boolean```): Whether the color is an accent color.
///
/// ==== Example
/// \<removed for brevity\>
///
/// - theme (string): The theme to get the palette for. The dict @@themes can be used to simplify this.
/// -> dictionary
#let get_palette(theme) = { ... }

This ends up looking like this (ignore the applied theming):

[Mc-Zen]

Hello @TimeTravelPenguin ,

I am not sure if I understand correctly what you want to do. Should the the types be inferred automatically? Or do you just want to add information about the dictionary structure manually and the issue is about the formatting?

[Mc-Zen]

Note that you can put another space before the list items to prevent them being recognized as parameter documentation

/// Description
///  - name (string): The name of the flavour // not recognized as a parameter
///
/// - theme (string): ...  // recognized as a parameter

[Mc-Zen]

Closing for now due to lack of response. Fell free to re-open this though!