Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

regexp: hard to find documentation for 'n' #14581

Closed
guywithnose opened this issue Mar 1, 2016 · 1 comment
Closed

regexp: hard to find documentation for 'n' #14581

guywithnose opened this issue Mar 1, 2016 · 1 comment

Comments

@guywithnose
Copy link

Please answer these questions before submitting your issue. Thanks!

  1. What version of Go are you using (go version)?
    go version go1.6 linux/amd64
  2. What operating system and processor architecture are you using (go env)?
    GOOS="linux"
    GOARCH="amd64"
  3. What did you do?
    (Use play.golang.org to provide a runnable example, if possible.)
    I read documentation at https://golang.org/pkg/regexp/#Regexp.FindAllStringSubmatch.
  4. What did you expect to see?
    I expected easy to find documentation for all parameters.
  5. What did you see instead?
    Instead I had difficulty discovering what the n parameter does.

Initially I ended up finding my answer on a stack overflow question, but later it was pointed out that the 'n' parameter is documented in the package level documentation. The package level documentation is well written and would have answered my question, but it is currently very difficult to find. Part of the problem is that it is within a paragraph so it is not easy to just browse to it and searching the page for 'n' is also not efficient.

Two solutions that come to mind are documenting the parameter on the functions that use it or maybe just renaming it to something searchable like count.

@ianlancetaylor ianlancetaylor changed the title Regexp documentation for 'n' regexp: hard to find documentation for 'n' Mar 1, 2016
@ianlancetaylor ianlancetaylor added this to the Go1.7 milestone Mar 1, 2016
@rsc
Copy link
Contributor

rsc commented May 18, 2016

I see:

func (re *Regexp) FindAllStringSubmatch(s string, n int) [][]string
    FindAllStringSubmatch is the 'All' version of FindStringSubmatch; it returns
    a slice of all successive matches of the expression, as defined by the 'All'
    description in the package comment. A return value of nil indicates no
    match.

It says "as defined by the 'All' description in the package comment". It sounds like you missed that clause, which I understand, but it's not clear that there's much to do. Docs will be misread, Stack Overflow and other sites will help.

@rsc rsc closed this as completed May 18, 2016
@golang golang locked and limited conversation to collaborators May 18, 2017
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

4 participants