# Documenting elements of a struct
**URL:** https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769
**Category:** New to Julia
**Tags:** documenter, struct
**Created:** [July 16, 2021, 7:32pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769 "2021-07-16T19:32:46Z")
**Posts on this page:** 20
**Page:** 1
### Author:  [@orome](https://discourse.julialang.org/u/orome)
#### Post date: [July 16, 2021, 7:32pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/1 "2021-07-16T19:32:46Z")
How do I document the members of a `struct` so that `Documenter` generates documentation for them?
```julia
"""
This is an X
"""
struct X
"This is a"
a::String
"This is b"
b::Char
"This is c"
c
end
```
---
### Author:  [@jzr](https://discourse.julialang.org/u/jzr)
#### Post date: [July 16, 2021, 8:01pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/2 "2021-07-16T20:01:56Z")
Fwiw some people feel that struct properties should be considered private and shouldn’t be publicly documented, preferring accessor functions instead.
---
### Author:  [@mthelm85](https://discourse.julialang.org/u/mthelm85)
#### Post date: [July 16, 2021, 8:10pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/3 "2021-07-16T20:10:39Z")
I have no idea if there’s a better/canonical way, but I’ve done something like this in the past:
```julia
"""
This is an `X`
# Fields
- a: First letter of the English alphabet
- b: Second letter of the English alphabet
- c: C is for cookie
"""
struct X
a::String
b::Char
c
end
```
This may be really frowned upon though, I don’t know 😁
---
### Author:  [@pdeffebach](https://discourse.julialang.org/u/pdeffebach)
#### Post date: [July 16, 2021, 8:12pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/4 "2021-07-16T20:12:04Z")
How would you want to access it? Keep in mind that once I do `X.a`, that’s just a `String`. Julia has no knowledge that `X.a` came from the struct `X`, without metaprogramming.
---
### Author:  [@orome](https://discourse.julialang.org/u/orome)
#### Post date: [July 16, 2021, 8:17pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/5 "2021-07-16T20:17:57Z")
True; but that’s irrelevant to the documentation, which is about what to expect when doing `X.a`.
---
### Author:  [@pdeffebach](https://discourse.julialang.org/u/pdeffebach)
#### Post date: [July 16, 2021, 8:19pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/6 "2021-07-16T20:19:48Z")
True, `? X.a` could be smart.
---
### Author:  [@orome](https://discourse.julialang.org/u/orome)
#### Post date: [July 16, 2021, 8:22pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/7 "2021-07-16T20:22:22Z")
That would be fine if they _were_ private (and required accessors) but as it is I can `X.a`, so it should be possible to document what to expect when doing that (e.g. `? X.a` should work).
---
### Author:  [@jzr](https://discourse.julialang.org/u/jzr)
#### Post date: [July 16, 2021, 8:28pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/8 "2021-07-16T20:28:24Z")
There is a difference between being considered private and _enforcing_ that the attributes are externally inaccessible. Julia considers some things nonpublic but doesn’t enforce their inaccessibility.
---
### Author:  [@orome](https://discourse.julialang.org/u/orome)
#### Post date: [July 16, 2021, 8:38pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/9 "2021-07-16T20:38:55Z")
Maybe I’m not (noob) seeing the wisdom of making it impossible to document (in the usual way) something that’s “considered” non-public if it in fact is publicly accessible.
---
### Author:  [@jzr](https://discourse.julialang.org/u/jzr)
#### Post date: [July 16, 2021, 8:47pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/10 "2021-07-16T20:47:54Z")
It doesn’t make much sense to me that we conflate “documented” with “guaranteed to be forward compatible”, but here we are.
---
### Author:  [@mike](https://discourse.julialang.org/u/mike)
#### Post date: [July 16, 2021, 8:53pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/11 "2021-07-16T20:53:41Z")
[https://github.com/JuliaDocs/DocStringExtensions.jl](https://github.com/JuliaDocs/DocStringExtensions.jl) has `FIELDS` and `TYPEDFIELDS` which can be used for automatically embedding field docs in the main docstring:
```julia
julia> using DocStringExtensions
julia> """
This is an X
$(FIELDS)
"""
struct X
"This is a"
a::String
"This is b"
b::Char
"This is c"
c
end
X
help?> X
search: X xor exp Expr exp2 exit axes expm1 exp10 export EXPORTS extrema exponent Exception expanduser ExponentialBackOff max Text nextpow nextind maximum nextprod maximum!
This is an X
• a
This is a
• b
This is b
• c
This is c
julia> """
This is an X
$(TYPEDFIELDS)
"""
struct X
"This is a"
a::String
"This is b"
b::Char
"This is c"
c
end
X
help?> X
search: X xor exp Expr exp2 exit axes expm1 exp10 export EXPORTS extrema exponent Exception expanduser ExponentialBackOff max Text nextpow nextind maximum nextprod maximum!
This is an X
• a::String
This is a
• b::Char
This is b
• c::Any
This is c
```
---
### Author:  [@orome](https://discourse.julialang.org/u/orome)
#### Post date: [July 16, 2021, 9:06pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/12 "2021-07-16T21:06:35Z")
That looks good.
But how do I use that to build docs. When I
```bash
cd MY_PKG
(...) pkg> activate .
julia> using Revise
julia> include("docs/make.jl")
```
(after `add DocStringExtensions` to `docs` and putting `using DocStringExtensions` in `make.jl`, both of which I assume are necessary) I get `ERROR: LoadError: UndefVarError: TYPEDFIELDS not defined`.
---
### Author:  [@mike](https://discourse.julialang.org/u/mike)
#### Post date: [July 17, 2021, 7:15am UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/13 "2021-07-17T07:15:13Z")
`using DocStringExtensions` needs to be placed in your package where you are using `TYPEDFIELDS`, not in `docs/make.jl`. (It also needs to be installed in your package, not your `docs` subdirectory’s `Project.toml`.)
---
### Author:  [@orome](https://discourse.julialang.org/u/orome)
#### Post date: [July 17, 2021, 10:31am UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/14 "2021-07-17T10:31:54Z")
Oh wow. So (again noob) I’m definitely not understanding something here: adding a dependency to my code I order to document it (especially considering how otherwise tidy the separate `doc` environment is) seems wrong.
I’m clearly trying to do something I’m not supposed to do.
---
### Author:  [@mike](https://discourse.julialang.org/u/mike)
#### Post date: [July 17, 2021, 11:51am UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/15 "2021-07-17T11:51:22Z")
> [@orome](#):
>
> adding a dependency to my code I order to document it (especially considering how otherwise tidy the separate `doc` environment is) seems wrong.
The `docs/Project.toml` environment is for building static documentation based on the contents of a package. That’s not the only place we want to be able to access docstrings for packages though. We also want to be able to query docstrings from a live REPL/editor. The “abbreviation” objects, such as `TYPEDFIELDS`, need to be visible inside your package where your docstrings are located to be able to do their thing, so putting them into a separate environment is not possible. They have to be imported into the package’s module to work.
---
### Author:  [@orome](https://discourse.julialang.org/u/orome)
#### Post date: [July 17, 2021, 3:09pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/16 "2021-07-17T15:09:25Z")
Yeah I see that now. Clearly my attempt to automatically document parts of structs in the way I’m used to isn’t Julian. (Again, novice here.) Having to make a documentation package a dependency is definitely (Julian or otherwise) not what I want to do.
---
### Author:  [@heetbeet](https://discourse.julialang.org/u/heetbeet)
#### Post date: [July 17, 2021, 4:57pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/17 "2021-07-17T16:57:27Z")
For the most part its not bad to add lightweight dependencies to a package. The mentioned package doesn’t just add a mechanism to generate documentation, but also annotates the struct with a docstring accessible from `help` and the like. If I were a user of your package, I would like getting that help in my REPL, no matter a small dependency. B.t.w. I agree with you that a public accessible thing should be easily documented. I’d say go for that package
Also, I just had a look at the source code, the src seems to be about ~1000 loc and the only secondary dependency is `LibGit2`
---
### Author:  [@orome](https://discourse.julialang.org/u/orome)
#### Post date: [July 17, 2021, 5:35pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/18 "2021-07-17T17:35:38Z")
I’m totally in agreement that any publicly accessible thing should be document (and a bit confused about the assertion that any such thing should ever be [“considered” private](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/2)), but I just can’t bring myself to include a dependency that isn’t strictly related to what my package does — especially when the same result can be [achieved (if trivially) without introducing](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/3) such a dependency.
---
### Author:  [@heetbeet](https://discourse.julialang.org/u/heetbeet)
#### Post date: [July 17, 2021, 7:39pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/19 "2021-07-17T19:39:04Z")
It’s good to not add lots of uneccesary dependencies (it can help with compilation time etc), so if you find the alternative sufficient, then stick with that. On the other hand, packages are there to be used, and Julia makes barrier to entry for dependencies really low. Julia also started moving lots of base code into seperate packages, like [Move SharedArrays to a package · Issue #23713 · JuliaLang/julia · GitHub](https://github.com/JuliaLang/julia/issues/23713) and encourages the community to expand and use the package infrastructure.
So basically all in moderation. You seem to know what you aim for, so stick with that
---
### Author:  [@orome](https://discourse.julialang.org/u/orome)
#### Post date: [July 17, 2021, 7:49pm UTC](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769/20 "2021-07-17T19:49:33Z")
Yeah I’ve got no problem with dependences. But putting a documentation dependence in the package itself feels wrong.
[Next page](https://discourse.julialang.org/t/documenting-elements-of-a-struct/64769.md?page=2)