Repository navigation
require: invalid examples from doc comments as functions don't return bool #1776
Description
Description
The doc comments for multiple functions in the require package have code examples that are invalid. Example:
Line 1391 in a53be35
The example reads:
if require.NoError(t, err) {
require.Equal(t, expectedObj, actualObj)
}but the NoError() function does not return any value, so this is invalid.
There are similar invalid examples in the doc comments for NoErrorf, NotEmpty and NotEmptyf.
Reacted by Olivier Mengué
Activity
brackendawson commentedon Aug 6, 2025
Same as #1609 for require.Error but we missed some. The require documentation is generated from the assert documentation. We either need to make the assert documentation work for both packages or stop generating the one from the other.
PCloud63514 commentedon Aug 8, 2025
Hello! I was wondering if this issue has already been resolved. Could you please confirm? Thank you!
#1675
fragglet commentedon Aug 8, 2025
No, #1675 fixed
require.Errorbut not the other functions I've listed above.PCloud63514 commentedon Aug 8, 2025
I'd like to contribute to resolving this issue!
In my opinion, even though
assertandrequireare similar, they have different responsibilities.Wouldn't it be better to maintain separate documentation for each?
brackendawson commentedon Aug 17, 2025
I've assigned you, @PCloud63514.
As with all things; maintaining separate docs is a trade-off. Most functions in require actually call their counterpart in assert, this ensures that they are identical. Most of the assert functions' docs convert cleanly to require. The error functions can have a doc example that converts cleanly, #1675 shows this. It's possible to move these functions to files outside of the generated files to have separate documentation, but we'd rather not maintain two identical sets of functions for these error assertions just to allow their docs to be different. It's also possible to do something else to use the same implementation but different docs, but in that case any update to the documentation might not notice that the require docs also need to be updated by hand.
I'll leave the implementation up to you. Propose a good trade-off and we'll consider it. Otherwise if you just update the docs to a version which converts cleanly I'd be happy merging that PR.
PCloud63514 commentedon Aug 20, 2025
@brackendawson Sorry for the late reply. 😅
I’m not sure if I expressed my point clearly before.
My view is that the responsibility of 'require' is to fail immediately, not to return a value.
Therefore, I believe updating the doc comments is the correct fix.
For this purpose, I have added a doc generation method for the require package.
I’ve opened a PR with the revised form!
ccoVeille commentedon Aug 21, 2025
The more I think about it, the more I feel we should remove all code from comment and use Go Example.
They can also be generated, but they can be formatted
[-]Examples from doc comments are invalid[/-][+]require: invalid examples from doc comments as functions don't return boo[/+][-]require: invalid examples from doc comments as functions don't return boo[/-][+]require: invalid examples from doc comments as functions don't return bool[/+]ccarcaci commentedon May 23, 2026
@dolmen
I was looking for a "good first issue" where to start contributing from. This one has been solved by the PR #1850
I guess this issue should be closed.
doc: record the upstream reports behind this round of fixes