beacon-biosignals / Legolas.jl

Tables.jl-friendly mechanisms for constructing, reading, writing, and validating Arrow tables against extensible, versioned, user-specified schemas.
Other
24 stars 2 forks source link

Autogenerated docstrings for `@version`-generated record types #75

Open omus opened 1 year ago

omus commented 1 year ago

It would be nice to provide some autogenerated docstrings for record types. Usually when the a Legolas record type is given a docstring the code used to generate the schema version is just copied into the docstring making maintaining the docstring annoying. Most likely we'll want to autogenerate a default docstring for Legolas record types but provide functionality such that it's easy to generate the docstring. One proposal for how we can handle this can be seen in: https://github.com/beacon-biosignals/Onda.jl/pull/137#issuecomment-1343178187

Split out from: https://github.com/beacon-biosignals/Legolas.jl/issues/10

omus commented 1 year ago

Quite possibly we can use DocStringExtensions.jl to provide most of the functionality we want. If supported we could write the following:

"""
    AnnotationV1

My amazing description.

# Fields

$(TYPEDFIELDS)
"""
@version AnnotationV1 begin
    "The UUID identifying the recording with which the annotation is associated."
    recording::UUID = UUID(recording)

    "The UUID identifying the annotation."
    id::UUID = UUID(id)

    "The annotation's time span within the recording."
    span::TimeSpan = TimeSpan(span)
end

This would require a change to the @version macro to handle the addition of docstrings on fields. Additionally, this would provide us a way of automatically documenting the RHS of the fields. We would need to provide our own docstring extension to provide this functionality.