doc: make tag explanation more specific and example discoverable

[GoogleCodeExporter]

What steps will reproduce the problem?
1.Read the section of the docs that say "The mapping of each section or 
variable name to fields is done either based on the "gcfg" struct tag or by 
matching the name of the section or variable, ignoring case."
2.Attempt to find example which uses struct tags
3.open issue against project ;)

What is the expected output? What do you see instead?
Either the description of the feature should be verbose enough to make an 
example unnecessary or an example should be present which clearly demonstrates 
the feature.

Original issue reported on code.google.com by datsun...@gmail.com on 17 Dec 2014 at 7:21

[GoogleCodeExporter]

Thanks for the feedback! There actually is an example here: 
http://godoc.org/code.google.com/p/gcfg#example-ReadStringInto--Tags , but it 
may not be particularly easy to find and understand for newcomers.

Tag handing is based on the convention established by encoding/json and other 
similar packages. When I added tag support, I was assuming most users would be 
familiar with this convention, so I just added a brief mention and a trivial 
example. But thinking again it is perfectly reasonable for users to try gcfg 
without having prior experience with encoding/json. (After all, a major part of 
my motivation for creating this package was that I didn't think JSON was best 
suited for configuration, so people thinking similarly could be expected to try 
gcfg before having tried encoding/json.)

Original comment by speter....@gmail.com on 19 Dec 2014 at 1:28

• Changed state: Accepted
• Added labels: Component-Docs, Type-Enhancement
• Removed labels: Type-Defect

[GoogleCodeExporter]

Ah my mistake! I totally missed that example, I did however find the test for 
this feature which answered my question. Thanks for your quick reply.

Original comment by datsun...@gmail.com on 19 Dec 2014 at 5:03

[GoogleCodeExporter]

Thanks for the report anyway, the fact that you missed it indicates that it 
could be made easier to discover, and that I was assuming too much of the 
reader. Leaving this issue to remind myself of these as areas to improve when I 
get around to revise the docs.

Original comment by speter....@gmail.com on 23 Jan 2015 at 12:30

• Changed title: doc: make tag explanation more specific and example discoverable