# Is it possible to use @example in docstrings?
**URL:** https://discourse.julialang.org/t/is-it-possible-to-use-example-in-docstrings/100383
**Category:** General Usage
**Tags:** question, documentation
**Created:** [June 15, 2023, 9:25am UTC](https://discourse.julialang.org/t/is-it-possible-to-use-example-in-docstrings/100383 "2023-06-15T09:25:25Z")
**Posts on this page:** 9
**Page:** 1
### Author:  [@Christopher\_Fisher](https://discourse.julialang.org/u/Christopher_Fisher)
#### Post date: [June 15, 2023, 9:25am UTC](https://discourse.julialang.org/t/is-it-possible-to-use-example-in-docstrings/100383/1 "2023-06-15T09:25:25Z")
I would like to use the `@example` in my docstrings so that it is displayed in the api section of the documentation. The code is displayed in the documentation, but not the output. Is there a way to make it work?
---
### Author:  [@jishnub](https://discourse.julialang.org/u/jishnub)
#### Post date: [June 15, 2023, 9:33am UTC](https://discourse.julialang.org/t/is-it-possible-to-use-example-in-docstrings/100383/2 "2023-06-15T09:33:31Z")
I think you may use the following
````julia
julia> """
A
Return A
# Examples
```julia
x = A()
```
"""
struct A end
A
help?> A
search: A Any any all abs ARGS ans axes atan asin asec any! all! acsc acot acos abs2 Array atanh atand asinh asind asech asecd ascii angle acsch acscd acoth acotd acosh acosd atexit
A
Return A
Examples
≡≡≡≡≡≡≡≡≡≡
x = A()
````
---
### Author:  [@gdalle](https://discourse.julialang.org/u/gdalle)
#### Post date: [June 15, 2023, 9:47am UTC](https://discourse.julialang.org/t/is-it-possible-to-use-example-in-docstrings/100383/3 "2023-06-15T09:47:38Z")
But I think the actual answer to your question is no, because doing so would amount to running code to display docstrings. This can be done while building the documentation with Documenter.jl, but as far as I know it is not possible in the language itself
---
### Author:  [@Christopher\_Fisher](https://discourse.julialang.org/u/Christopher_Fisher)
#### Post date: [June 15, 2023, 10:08am UTC](https://discourse.julialang.org/t/is-it-possible-to-use-example-in-docstrings/100383/4 "2023-06-15T10:08:16Z")
Thank you for your replies. Just to clarify, I do not want to run the examples as code in the REPL. Instead, I would like it to display in the documentation that Documenter.jl produces via `@autodocs`. Currently, it only displays the code, but not the output. However, if I use `@example` directly in an .md file, it works.
---
### Author:  [@Christopher\_Fisher](https://discourse.julialang.org/u/Christopher_Fisher)
#### Post date: [June 15, 2023, 10:33am UTC](https://discourse.julialang.org/t/is-it-possible-to-use-example-in-docstrings/100383/5 "2023-06-15T10:33:16Z")
As a concrete [example](https://itsdfish.github.io/ACTRModels.jl/dev/api/), the documentation for `ACTR` (top of the page) generated by `@autodocs` does not run the example.
---
### Author:  [@gdalle](https://discourse.julialang.org/u/gdalle)
#### Post date: [June 15, 2023, 10:54am UTC](https://discourse.julialang.org/t/is-it-possible-to-use-example-in-docstrings/100383/8 "2023-06-15T10:54:11Z")
OK I misunderstood your question but I think my answer might still be valid. If I understand correctly, `@autodocs` copies the docstring (as does the REPL help mode) while `@example` runs it during docs build. It could be a nice feature request for Documenter though.
---
### Author:  [@Christopher\_Fisher](https://discourse.julialang.org/u/Christopher_Fisher)
#### Post date: [June 15, 2023, 11:41am UTC](https://discourse.julialang.org/t/is-it-possible-to-use-example-in-docstrings/100383/9 "2023-06-15T11:41:46Z")
Thanks again for your reply. I will submit a feature request. I don’t know if this is difficult to achieve from a technical perspective, but it could be useful, and from the perspective of a user, I expected it to work.
---
### Author:  [@mortenpi](https://discourse.julialang.org/u/mortenpi)
#### Post date: [June 16, 2023, 12:21am UTC](https://discourse.julialang.org/t/is-it-possible-to-use-example-in-docstrings/100383/10 "2023-06-16T00:21:58Z")
I don’t think we want this behavior in Documenter (it has been discussed before). Documenter’s goal is to reflect the docstrings as they appear in other contexts too (REPL, IDE docs browsers etc). Dynamic stuff in docstrings is usually handled by things like [DocStringExtension](https://github.com/JuliaDocs/DocStringExtensions.jl).
The options here would be either to (a) put the examples near the docstring in the manual, and refer to them in the docstring, or (b) for text-only outputs, you can use doctests in the docstrings (and doctests make sure they’re always up to date; and can also update the snippets for you).
---
### Author:  [@seabbs](https://discourse.julialang.org/u/seabbs)
#### Post date: [July 4, 2024, 2:33pm UTC](https://discourse.julialang.org/t/is-it-possible-to-use-example-in-docstrings/100383/11 "2024-07-04T14:33:57Z")
For interest coming from R I also expected this to just work and was surprised that it didn’t.
I can see the argument for why you want docstrings to be represented as they are but it does then make for quite a clunky work flow of needing a md file with some docs (like the examples) and also a docstring (unless I am misunderstanding).
Perhaps a solution is a doc update to reflect the expected documentation approach that supports @example and/or a link out to the part of `DocStringExtension` that would allow you too get the desired effect.