<p>I know it's because I'm a noob, but maybe I'm not alone .. I find godocs leave me cold.</p>
<p>Coming from Perl, I can instantly get a gist of a lib by looking at the CPAN documentation. The authors go to a lot of trouble to show a quickstart, as well as show more advanced examples. This allows for a quick appraisal of its suitability.</p>
<p>CPAN is not perfect, but the go documentation is done by robots and its way too clinical for me. I'd love to see someonething like a CGAN. Perhaps its already there .. any pointers?</p>
<hr/>**评论：**<br/><br/>TheMerovius: <pre><p>I really like <a href="http://godoc.org/" rel="nofollow">http://godoc.org/</a>. I prefer it over every other documentation I have ever seen. Simply because static analysis makes it possible to follow identifiers directly and the organisation of the page is good (though not always perfect), i.e. I can look at a package, find the type or function that appears to do what I need and then, simply by following links, how I can create all the arguments and preconditions to use it. It's <em>so</em> much easier than anything I've seen so far.</p>
<p>Bad documentation is a problem, but I find with the go way that even bad documentation is still enough, often, to get going fast.</p>
<p>Also note, that you <em>can</em> make good documentation with godoc. You can create an overview description, you can create examples, you can do everything you need.</p>
<p>I <em>much</em> prefer the go way. It is the best solution I have seen so far both to the distribution problem of packages and the documentation problem…</p></pre>jerf: <pre><p>I'd point out I've had better luck searching on godoc.org than I have on Google. A couple of times now I've done my due diligence on Google, found out nothing seems to exist for some problem (or only very incomplete solutions), and only after finishing it discovering on godoc.org that a better solution existed.</p>
<p>godoc.org is really the answer to the question right now. It's still not "CPAN", but, well, CPAN doesn't always live up to its own reputation, either. Get away from the "main" packages and you're just as much in the weeds as in any other language.</p></pre>tclineks: <pre><p>I always thought of CPAN more as a distribution mechanism.
Quality of documentation isn't affected by how you render it nearly as much as the effort that has gone into it.</p>
<p>Maybe this is a good opportunity to encourage library authors to provide better examples or even contribute some docs.</p></pre>robertmeta: <pre><p>I really don't want package centralization. There are those that do, and CPAN is maybe one of the best examples of such a system. But in 2015, you are far more likely to get NPM than another CPAN. CPAN was a property of its time. NPM is a single source of failure, that was flipped into revenue generating opportunity once the community couldn't live without it.</p>
<p>As for documentation (which is entirely separate from the centralization issue)... the "Go Style" is very rough on beginners. The terse (and often interrelated) style of go documentation is one of those things that is a huge pain early, but quickly fades away as you get used to it. I can often get the gist of something by reading a blurb on <a href="https://godoc.org/" rel="nofollow">https://godoc.org/</a></p></pre>XANi_: <pre><p>Package centralisation is bad, sure, but one of best points of CPAN is that I can click on say <a href="http://www.cpantesters.org/distro/S/Search-Elasticsearch.html#Search-Elasticsearch-1.99" rel="nofollow">here</a> and get a report of all the tests given version of lib has passed, <strong>and</strong> get a same for all of its <a href="http://deps.cpantesters.org/?module=Search%3A%3AElasticsearch;perl=latest" rel="nofollow">deps</a></p></pre>intermernet: <pre><p>It's really up to individual authors to provide more advanced / detailed docs. One useful practice is to have a <code>doc.go</code> file in the package that contains more detailed documentation such as examples etc. For example the <code>pq</code> package has <a href="https://github.com/lib/pq/blob/master/doc.go" rel="nofollow">https://github.com/lib/pq/blob/master/doc.go</a> which provides the example code etc. seen at <a href="http://godoc.org/github.com/lib/pq" rel="nofollow">http://godoc.org/github.com/lib/pq</a> .</p>
<p>More info at <a href="http://blog.golang.org/godoc-documenting-go-code" rel="nofollow">http://blog.golang.org/godoc-documenting-go-code</a></p></pre>jjolla888: <pre><blockquote>
<p>the pq package</p>
</blockquote>
<p>is exactly what i am looking for. If every package contained this level of documentation i'd be as happy as a pig in mud</p>
<p>i am not sure of the requirements of CPAN, but i suspect authors have to go thru some hoops to get their code published there. So the missing bit is having some type of reward or incentive to create good doc.go documents.</p>
<p>I guess it's early days and it's only going to get better</p>
<p>Thanks for the pq pointer, i'm going to find it useful</p></pre>WAL1D: <pre><p>I didn't understand nothing in documentation, but mail list and the Stackoverflow work.</p></pre>gdey: <pre><p>As people have mentioned there is a convention to use doc.go to put the level of documentation that is typically found in CPAN modules via POD. Go's documentation standard has somethings I'm hoping Perl will steal, especially the examples. You can a file called *_example.go with comments showing what the output should be, that not only becomes a test; but is also a runnable example in godoc.org. (Look here for a better explanation <a href="http://blog.golang.org/examples" rel="nofollow">http://blog.golang.org/examples</a>) Really nice stuff. But as people have mentioned to get that level of documentation there needs to be a culture around it. Perl has created that culture by providing all the tooling that comes with it. When you upload a module to CPAN you get all sorts of things like coverage reports; on a variety of platforms, as well as remarks on the quality of documentation, all without much effort on the Authors part. </p>
<p>To this end, the San Diego Gophers has put a proposal to enhance godoc.org to provide an way to rank and categorize packages (based on various tools (go vet, go lint, etc) something akin to <a href="http://goreportcard.com/report/" rel="nofollow">goreportcard</a>). The idea is to make it easier to find great packages, and to encourage package authors to put the extra effort to make their package even better; by quickly providing way in which they can improve their package. Basic low hanging fruit. A lot of this is already provided by the basic tool go provides. We are just make it more visible. The proposal was just submitted for review; and hopefully we can open it up to the community, soon, to get feedback.</p>
<p>I like the fact that it's really easy to share a package in go. The decentralized aspects of it are wonderful, and do avoid many of the pit falls of having a central repo. Going this route allows enterprises to setup an internal godoc.org site point to their internal repos easily; getting the same benefits as the public godoc.org site. This can only help adoption of Go in enterprises. And increases the number of possible contributor to image the site better. </p>
<p>Doing this for CPAN is a pain. And though my current company has managed to do it; it was still a pain. NPM is a nightmare in this regard.</p></pre>XANi_: <pre><p>Hint: godoc.org/<strong>any address on the internet</strong> will go there, check if it looks like a go repo and make a documentation out of it if it does.</p>
<p>so if you find <strong>any</strong> lib on github you can just go to <code>godoc.org/github.com/repo/name</code> and get a docs for it</p></pre>f2f: <pre><p>do you have a real question? show us what the problem is, perhaps we can help you. many people find the documentation in its current state sufficient. it's not geared towards hotshot newbies, but it works out really well in the long term.</p></pre>jjolla888: <pre><p>ok here goes .. i think i nearly have a working program but i am sure it is way inefficient .. would love to know how you would do it.</p>
<p>Simply, i have a file which is binary .. but inside it there is a token "EOF\n". I know this exists somewhere inside it.</p>
<p>What i need to do is split the file into two -- one file with all the contents up to EOF\n, and another with all the contents after it.</p>
<p>Thanks!!</p></pre>calebdoxsey: <pre><p>How about:</p>
<pre><code>package main
import (
"bufio"
"fmt"
"io"
"io/ioutil"
"os"
"regexp"
)
func splitFile(token string, src, dst1, dst2 *os.File) error {
// for a file you'll want to use bufio so it buffers it in chunks
rdr := bufio.NewReader(src)
// we can search using the regexp package
re, err := regexp.Compile(regexp.QuoteMeta(token))
if err != nil {
return err
}
// it supports searching over a RuneReader, which buf
loc := re.FindReaderIndex(rdr)
// the docs say: The match text was found in the input stream at
// byte offset loc[0] through loc[1]-1. A return value of nil indicates
// no match.
if loc == nil {
return fmt.Errorf("token not found")
}
// files implement the Seeker interface: https://golang.org/pkg/io/#Seeker
// first go to the beginning of the file (because we're in the middle
// right now):
_, err = src.Seek(0, 0)
if err != nil {
return err
}
// use limit reader to only read the first part
first := io.LimitReader(src, int64(loc[0]))
_, err = io.Copy(dst1, first)
if err != nil {
return err
}
// Now seek to the next piece
_, err = src.Seek(int64(loc[1]), 0)
if err != nil {
return err
}
// No need to limit here because it goes to the end of the file
second := src
_, err = io.Copy(dst2, second)
if err != nil {
return err
}
return nil
}
func main() {
ioutil.WriteFile("src.txt", []byte(string("abcEOF\nxyz")), 0666)
// use os.Open(...) to open the file
src, err := os.Open("src.txt")
if err != nil {
panic(err)
}
defer src.Close() // remember to close them, defer makes this easier
// use os.Create(...) to create files
dst1, err := os.Create("first.txt")
if err != nil {
panic(err)
}
defer dst1.Close()
dst2, err := os.Create("second.txt")
if err != nil {
panic(err)
}
defer dst2.Close()
err = splitFile("EOF\n", src, dst1, dst2)
if err != nil {
panic(err)
}
}
</code></pre></pre>jjolla888: <pre><p>fantastic! thanks so much for the pointers</p>
<p>i forgot to mention that the file i am reading is oversize ... many GB .. so a single pass without slurping everyghing in is desirable. So, with that in mind, I've created a version that reads one char at a time .. i'm assuming the file system is buffering so i don't need to go to any fancy reading large buffers and managing all that shenanigans.</p>
<p>Anyway, the below seems to work ... let me know anything that is blatantly bad:</p>
<pre><code> package main
import ( "bufio" ; "fmt" ; "os" )
const token = "EOF\n"
var bytes_matched = int(0)
var found_token = false
var bytes_read = int(0)
const debug = true
func main() {
reader := bufio.NewReader(os.Stdin)
outf,err := os.Create( "part1.bin" ) ; che(err)
writer := bufio.NewWriter(outf)
second_file := false
for {
b,err := reader.ReadByte()
if err != nil {; break } // reached EOF
bytes_read++
err = writer.WriteByte(b) ; che(err)
if !second_file {
if !found_token {
running_match(b)
if found_token {
writer.Flush()
outf.Close()
outf,err = os.Create( "part2.bin" ) ; che(err)
writer = bufio.NewWriter(outf)
second_file = true
}
}
}
}
writer.Flush()
outf.Close()
}
func running_match(b byte) {
// bytes_matched and found_token are global variables
// updated by this func
// check the current byte matches
// the 1+last matched pos in the token
// so if b==E, we will add 1 to the "bytes_matched"
// if the next b==O, then bytes_matched will be increased to 2
// if the next b!=F, bytes_matched will be reset to zero
// this func should never be called once we have a full match
if bytes_matched >= 4 {
if debug {; fmt.Println("should never be called !!") }
found_token = true
return
}
if b == token[bytes_matched] {
bytes_matched++
if bytes_matched == 4 {; found_token = true }
}else{
bytes_matched = 0 //reset
}
// debug
if debug && bytes_matched > 0 {; fmt.Println(bytes_read,bytes_matched) }
}
// func to save me having to type
func che(e error) {
if e!= nil {; panic(e) }
}
</code></pre>
<p>edit: changed the misleading name of a variable</p></pre>TurquoiseTurkey: <pre><p>This would be a big plus, but the Go authors' centralized mentality is unlikely to produce it. So users will have to set it up themselves.</p></pre>MindyStevens: <pre><p>godoc.org was setup by a user. motivated user can setup cgan.</p></pre>tvmaly: <pre><p>I had the same thought the other day, but cgan.org was taken. POD docs are definitely easier to read compared to godoc but they do take more effort to write. CPAN is centralized but that is a good thing as they do try to archive modules by author. It helps to build a reputation and trust in a way compared to github.</p></pre>
