Skip to content

Conversation

@Alizter
Copy link
Collaborator

@Alizter Alizter commented Nov 14, 2025

A common issue we have is undocumented arguments. It doesn't help that cmdliner hides the doc argument making it easy to miss. This is a common point of confusion for users #12722. In order to aid this we make the argument explicit. This makes it more apparent what is documented and what isn't.

@Alizter Alizter marked this pull request as ready for review November 14, 2025 17:49
Copy link
Collaborator

@Leonidas-from-XIV Leonidas-from-XIV left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's a reasonable change. Maybe it would be good to add a comment in places where ~doc:None exists with the TODO of adding documentation?

@Alizter
Copy link
Collaborator Author

Alizter commented Nov 17, 2025

I would regard any ~doc:None as a TODO for documentation from this point on. Leaving things undocumented only causes confusion for users, so we don't have a good reason to leave doc as None.

@Leonidas-from-XIV
Copy link
Collaborator

Yeah, but it is hard to search for and hard to know for readers so having a (* CR-later: document argument *) or so would be nice as it signals to readers of the source that documentation is to be added and is not intentionally undocumented.

@Alizter Alizter force-pushed the push-otoorxulyurv branch 2 times, most recently from 194e8df to 8bbec0e Compare November 17, 2025 10:52
Copy link
Collaborator

@Leonidas-from-XIV Leonidas-from-XIV left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! I think except for the boot/libs.ml change this is good to go.

@Alizter
Copy link
Collaborator Author

Alizter commented Nov 17, 2025

There are around 20 arguments undocumented. I think many of these have a sensible documentation, I'll try to get them done eventually. (After this PR)

@Leonidas-from-XIV Leonidas-from-XIV enabled auto-merge (squash) November 17, 2025 11:00
@Leonidas-from-XIV Leonidas-from-XIV merged commit 13f34ff into ocaml:main Nov 17, 2025
26 checks passed
@Alizter Alizter deleted the push-otoorxulyurv branch November 17, 2025 11:29
ElectreAAS added a commit to MixiMaxiMouse/dune that referenced this pull request Nov 17, 2025
Signed-off-by: Ambre Austen Suhamy <[email protected]>
ElectreAAS added a commit to MixiMaxiMouse/dune that referenced this pull request Nov 26, 2025
Signed-off-by: Ambre Austen Suhamy <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants