Print all fields docstrings not just the struct docstring.

[Ismael-VC]

In Python it's default to print all of the inner objects docstrings contained within a class, for example methods, along with the class docstring:

In [1]: class Foo:
   ...:     "Foo class."
   ...:     def foo():
   ...:         "Foo.foo method."
   ...:         pass
   ...:     def bar():
   ...:         "Foo.bar method."
   ...:         pass
   ...:
   ...:

In [2]: help(Foo)
Help on class Foo in module __main__:

class Foo
 |  Foo class.
 |
 |  Methods defined here:
 |
 |  bar()
 |      Foo.bar method.
 |
 |  foo()
 |      Foo.foo method.
(END)

Currently in Julia, you can document each field, but in order to see it's documentation you have to query help> using the complete reference to that field. ie:

julia> "Foo struct."
       struct Foo
           "foo field."
           foo
           "bar field."
           bar
       end
Foo

help?> Foo
search: floor pointer_from_objref OverflowError RoundFromZero unsafe_copyto! functionloc StackOverflowError @functionloc Factorization OutOfMemoryError

  Foo struct.


help?> Foo.foo
  foo field.


help?> Foo.bar
  bar field.


julia>

I think printing all in one go is far more useful (possibly also piping the output through a pager, like python does?), something like this:

help?> Foo
search: floor pointer_from_objref OverflowError RoundFromZero unsafe_copyto! functionloc StackOverflowError @functionloc Factorization OutOfMemoryError

  Foo struct.
      foo field.
      bar field.

julia>

[asinghvi17]

bump?

[adigitoleo]

At least some kind of introspection of field docstrings is necessary for this (and seems to be missing currently, see e.g. #29478). I just slapped together a function to generate a markdown table based on the fields, but I can only do names and types AFAIK. It could probably be improved, I'm very new to Julia...

julia> """This is Foo

       $(mdtable(Foo))

       """
       struct Foo
           """This is the first field"""
           first
           """This is the second field"""
           second
       end
Foo

help?> Foo
search: Foo floor pointer_from_objref transform_polarization OverflowError RoundFromZero unsafe_copyto!

  This is Foo

  Field  Type
  –––––– ––––
  first  Any
  second Any

Source for mdtable:

"""
    mdtable(t::NamedTuple)::String
    mdtable(t::DataType)::String

Create a markdown formatted table from a `NamedTuple`,
or generate it automatically for the field names and types of a `DataType`.

"""
function mdtable(t::NamedTuple)::String
    widths = Vector{Int}(undef, length(t))
    cols = Vector{Vector{String}}(undef, length(t))
    for (index, colname) in enumerate(keys(t))
        column = pushfirst!(String.(t[colname]), String(colname))
        widths[index] = maximum(length.(column))
        cols[index] = rpad.(column, widths[index])
    end
    out::String = ""
    hrule::String = "|:" * join([repeat("-", w) for w in widths], ":|:") * ":|\n"
    for (index, row) in enumerate(collect(eachrow(hcat(cols...))))
        out = out * "| " * join(row, " | ") * " |\n"
        if index == 1
            out = out * hrule
        end
    end
    return out
end
mdtable(t::DataType)::String = mdtable(
    (;
        (
            name => [col...] for
            (name, col) in zip((:Field, :Type), [fieldnames(t), nameof.(fieldtypes(t))])
        )...,
    ),
)

[MichaelHatherly]

Since it's not been linked back to here I'll point out FIELDS and TYPEDFIELDS from https://github.com/JuliaDocs/DocStringExtensions.jl which do this:

julia> using DocStringExtensions

julia> """This is Foo

       $(FIELDS)

       """
       struct Foo
           """This is the first field"""
           first
           """This is the second field"""
           second
       end
Foo

help?> Foo
search: Foo floor pointer_from_objref OverflowError RoundFromZero unsafe_copyto! functionloc StackOverflowError @functionloc OutOfMemoryError UndefKeywordError

  This is Foo

    •  first
       This is the first field

    •  second
       This is the second field

There's an open issue, JuliaDocs/DocStringExtensions.jl#92, regarding merging (some amount of) the package into Base. (I'm still of the opinion that there isn't really a strong enough case for doing so though.)

[adigitoleo]

@MichaelHatherly Thanks for the package! Even if it's outside of Base that's still a much more sensible idea than rolling our own string interpolations.