Go: text/scanner: add examples

[awoodbeck]

I recently worked with the text/scanner package and, although the documentation was straight forward, it could stand to use more examples.

I've been looking for opportunities to contribute to Go and I wouldn't mind working on improving the examples of the text/scanner package. I would like to add examples detailing the use of white space modifiers and tokens, as well as the various scanner and position methods. I would keep each example succinct, of course.

Are there particular guidelines to follow when it comes to examples?

[ALTree]

• for package-level examples, I would go with high-level, broad, well commented examples that show how to use the text/scanner package to accomplish something. Like the ones you can see for the sort package under the Overview section here: https://golang.org/pkg/sort/

• for function-level examples, I would go with small, ideally auto-contained snippets that show how to setup and call the function. I suggest don't bothering to do this for functions that are extremely easy to use. An example that shows how to call a math function that take one argument, like this sq := math.Sqrt(x) is not useful.

You don't have to do both. For example, if you find that the text/scanner package would mostly benefit from just package-level examples, just add package-level examples.

[awoodbeck]

Is it most appropriate to post examples here for discussion before opening a CL?

[andybons]

You should just open a CL.

Generally we ask that people don’t send code reviews until it’s agreed upon that a proposal should be implemented (adding a new package, changing something non-trivial). For documentation changes like adding examples, it’s reasonable to simply send out the code review and have a discussion there.

[gopherbot]

Change https://golang.org/cl/93199 mentions this issue: text/scanner: add examples

[awoodbeck]

Is there anything I can do to facilitate a review of my CL? I'm new to the Golang CL process and don't know really what to expect.

[ALTree]

According to the owners file, Robert owns the text/scanner package. Add him ([email protected]) as a reviewer in the CL on gerrit using the ADD REVIEWER button.