Discussion: code examples (/ snippets) in docstrings?

[cglacet]

Allow to have code examples (/ snippets) in docstrings
I'm using the |; ;| comments to document function behaviors, but I'd like to show code examples.

Describe the solution you'd like
I know many other language have support for this through things like a @Example tag. Or somtimes simply by providing markdown support in their docstring.

So it might be something like:

;| 
    A nice function
    @Param x int: the x param is an int
    @Example
        (f 2)
|; 
(defun f (x)
    (* 2 x)
)

Which should render in the tooltip as :

f [?]

A nice function

---

(f x)

---

@Example

(f 2)

---

@param — x int

---

@returns — int: twice x

---

source — some_file.lsp

An alternative input (maybe cleaner and simpler) :

;| 
    A nice function
    @Param x int: the x param is an int
    @Example Here is how you could use `f`
    ```lisp
    (f 2)
    ```
|; 
(defun f (x)
    (* 2 x)
)

The idea here would simply be to render any markdown "under" the @Example and let the user embed code blocs if he wants to.
In that particular case, the example section would render:

---

@Example

Here is how you could use f

(f 2)

---

Describe alternatives you've considered
I've tried many things but I can't even manage to include linebreaks (in the output) which makes it quite hard to structure the tooltips for the function's users. Maybe the best thing I could do is to use the @Remarks section and embbed a oneliner using single quotes like so:

;| 
    A nice function
    @Param x int: the x param is an int
    @Remarks Here is how you could use the `f` function: `(f 2)`
|; 
(defun f(x) ...)

But it only really works for oneliners, not for more complex code examples.

Additional context
Here is how it looks for typescript:

/**
 * A powerful function
 * @param x is crucial for calculation
 * @returns something important
 * @example
 * 
 * f(2) // returns 4
 */
function f(x: number): number {
    return 2*x;
}

Which renders :

[qiuradsk]

#271