docs(assert/require): clarify allowed rx values for Regexp/NotRegexp (#268, #1793) #1817
Conversation
Signed-off-by: kdt523 <[email protected]>
… checks Signed-off-by: kdt523 <[email protected]>
…puts Signed-off-by: kdt523 <[email protected]>
…mment line Signed-off-by: kdt523 <[email protected]>
|
|
||
| // Lenf asserts that the specified object has specific length. | ||
| // Lenf also fails if the object has a type that len() not accept. | ||
| // Len also fails if the object has a type that len() not accept. |
There was a problem hiding this comment.
This change seems unexpected
There was a problem hiding this comment.
Hi @ccoVeille, thanks for catching that! The comment was updated to clarify that both [Lenf] and [Len] will fail if the object’s type isn’t accepted by Go’s built-in [len()] function. This makes the documentation more explicit for users who might be unsure about which types are supported. If you think the wording could be improved or if it’s redundant, I’m happy to adjust further.
| // Regexp asserts that a specified regexp matches a string. | ||
| // | ||
| // The rx (expression) argument should be a *regexp.Regexp. For backward | ||
| // compatibility, if rx is any other type, its value will be formatted with | ||
| // %v and compiled using regexp.Compile. |
There was a problem hiding this comment.
I would use godoc links
| // Regexp asserts that a specified regexp matches a string. | |
| // | |
| // The rx (expression) argument should be a *regexp.Regexp. For backward | |
| // compatibility, if rx is any other type, its value will be formatted with | |
| // %v and compiled using regexp.Compile. | |
| // Regexp asserts that a specified regexp matches a string. | |
| // | |
| // The rx (expression) argument should be a [*regexp.Regexp]. For backward | |
| // compatibility, if rx is any other type, its value will be formatted with | |
| // %v and compiled using [regexp.Compile]. |
There was a problem hiding this comment.
Thanks for the suggestion, @ccoVeille! I’ve updated the doc comments to use GoDoc link syntax for both [regexp.Regexp] and [regexp.Compile] as you recommended. This should make the documentation clearer and more helpful for users. Let me know if you have any other feedback
2 participants
docs(assert/require): clarify allowed rx values for Regexp/NotRegexp (#268, #1793)
Summary
Clarify the allowed types and runtime behavior of the rx argument for assert.Regexp, assert.NotRegexp and their require and *f variants. This is a documentation-only change.
Changes
Updated function comments in:
assert/assertions.go
assert/assertion_format.go
assert/assertion_forward.go
require/require.go
require/require_forward.go
The comments now:
State that the preferred rx value is a *regexp.Regexp.
Explain that non-*regexp.Regexp values are stringified and compiled (historical behavior preserved).
Motivation
Users were unclear about which types are accepted for the rx parameter and whether passing a plain string or other value was supported. The code historically accepts interface{} and falls back to stringifying and compiling the value; documenting this explicitly reduces confusion and helps callers choose the safest/most efficient usage (passing a compiled *regexp.Regexp when possible).
Related issues
#1793
Behavior / Tests
Behavior: No runtime or API behavior changes were made. The implementation still stringifies non-*regexp.Regexp values and compiles them with regexp.MustCompile (same as before). This PR is documentation-only.
Tests: I ran package tests for the changed packages locally:
go test ./assert ./require — passed.
Note: Running go test d:. on Windows may show failures in suite due to environment-specific tests (panic/restart tests and -race subprocess builds needing a C toolchain). Those failures are unrelated to this docs-only change.