How to programmatically access documentation for fields of a composite type?


#1

Assuming code like this:

"This is a struct"
struct Bla
    "it has a field"
   a_field
end

bla = Bla(42)

How do I access the documentation of Bla.a_field from within a program (I know how to get it at the REPL)? I can use the functions in Base.Docs (e.g. @doc) to access the doc string for Bla, but I haven’t found a way to do it for Bla.a_field.

For context: I want to automatically generate command line options from a Parameters object, using the documentation of the fields of the object to document the command line options.


#2

REPL.fielddoc, in action: https://github.com/mauro3/Parameters.jl/blob/870131fa4114af141b4c40d8275259e5d19e444b/test/runtests.jl#L34

Note sure whether this is the best way though.


#3
julia> foreach(f -> print("$f -- $(REPL.fielddoc(Bla, f))"), fieldnames(Bla))

a_field -- it has a field

#4

Thanks, that solves my problem. That said, this solution is a lot of things, but definitely not pretty… If this is indeed the only way to access that information maybe I should file a bug report.


#5

It doesn’t look like a bug to me, nor particularly ugly. Possibly it could be made more easily available in Docs instead of REPL (if it isn’t already). What do you consider problematic about it, and what would you suggest to improve it?


#6

Yep, that it is in REPL.


#7

I agree, you shouldn’t have to go through REPL to access parts of the documentation. Plus Docs.@doc should be able to find all documentation.


#8

For reference, mauro’s (open) bug report from May last year:

https://github.com/JuliaLang/julia/issues/27092


#9

It’s not the only way, and you don’t have to go through REPL, you can get it from Docs.meta, although it’s not as nicely packaged as fielddoc. As for @doc, yes I agree it’d be nice, although I would call that a “missing feature”, not a “bug”. Marking words perhaps, but many programmers are quite sensitive to that distinction :slight_smile:


#10

It’s not the only way, and you don’t have to go through REPL , you can get it from Docs.meta

And then someone decides to change the internal representation of the meta data and my code stops working. There’s a reason for stable, easily accessible APIs.

In any case, the issue has been known for a year, so apart from fixing it myself there’s really not much to do about it right now.


#11

Precisely :wink: Most issues get fixed by people who are most bothered by them.