[Clarification] Precedence of helptext generation.

[emcd]

Comments on lines above attributes take precedence over the docstrings on the classes for those attributes. Example:

@dataclass
class Cli:
    application: ApplicationInformation
    configfile: Optional[ str ] = None
    # display: ConsoleDisplay
    inscription: InscriptionControl = (
        InscriptionControl( mode = InscriptionModes.Rich ) )
    command: Union[
        Annotated[
            _create.Command,
            tyro.conf.subcommand( # pyright: ignore
                'create', prefix_name = False ),
        ],
        Annotated[
            _apply.Command,
            tyro.conf.subcommand( # pyright: ignore
                'apply', prefix_name = False ),
        ],
    ]

results in:

╭─ options ────────────────────────────────────────────────────────────────────╮
│ -h, --help              show this help message and exit                      │
│ --configfile {None}|STR                                                      │
│                         (default: None)                                      │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ application options ────────────────────────────────────────────────────────╮
│ Information about an application.                                            │
│ ──────────────────────────────────────────────────────────────────────────── │
│ --application.name STR  (default: foo)                                       │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ inscription options ────────────────────────────────────────────────────────╮
│ display: ConsoleDisplay                                                      │
│ ──────────────────────────────────────────────────────────────────────────── │
│ --inscription.mode {null,pass,rich}                                          │
│                         (default: rich)                                      │
│ --inscription.level {None,debug,info,warn,error,critical}                    │
│                         (default: None)                                      │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ subcommands ────────────────────────────────────────────────────────────────╮
│ display: ConsoleDisplay                                                      │
│ ──────────────────────────────────────────────────────────────────────────── │
│ {create,apply} 

However, similar to ApplicationInformation, InscriptionControl has a docstring on the class:

@dataclass
class ApplicationInformation:
    ''' Information about an application. '''

@dataclass
class InscriptionControl:
    ''' Logging and debug printing behavior. '''

But, only the docstring for ApplicationInformation shows correctly. The docstring for InscriptionControl is occluded by the commented field.

Is this desired behavior? If so, should it be clarified in https://brentyi.github.io/tyro/helptext_generation/?

Also, would you consider it useful to have another tyro.conf annotation to suppress this behavior? As someone who frequently scaffolds code and leaves in TODO comments, I've been annoyed by scaffolding comments showing up as helptext on more than one occasion.

[brentyi]

Hi @emcd! This is as-designed, but I see why it's annoying. The reason is that the comment is treated as a "docstring" for the field, and we treat field docstrings as "more specific" than class docstrings.

For moving forward: adding a flag to turn off comment scraping is non-invasive and I'm happy to do it. We could also revisit the specific default behaviors, although my guess is that all possible choices here just leads to different tradeoffs and there's no objective right thing to do.

[emcd]

@brentyi : You have an amazing turnaround time. Thanks for the PR. I was going to offer to make it if you were amenable to the new flag, but am not going to complain if the project maintainer spontaneously produces patches instead. :)

To be clear, I am not interested in changing the defaults. I agree that there is no objective right thing to do here. Was mainly seeking clarification on the order of precedence... attribute-specific over class docstring makes sense. I don't recall that being explicitly mentioned in the documentation on helptext generation though.