Package Declaration Comments

[simeonwillbanks]

Comments on package declarations should provide general package documentation.

-- "Godoc: documenting Go code"

Comments on package declarations can be in a few places:

1. doc.go

• "Godoc: documenting Go code" says, "...for packages that need large amounts of introductory documentation: the package comment is placed in its own file, doc.go, which contains only those comments and a package clause."
• example

2. grohl.go
   • "Godoc: documenting Go code" says, "These comments can be short..."
   • example

Because we have a README.md, grohl.go seems best; the package comment can be short. The README.md can be nicely curated with examples, build status, contributors, etc. Godoc can be hosted by godoc.org. Once we're ready to release, we can add Grohl to godoc.org. Thoughts?

FWIW, I experimented with auto-generating the README.md from doc.go, but it requires a Godoc to Markdown converter. It seems overkill since godoc.org does a fine job of displaying Godoc.

[technoweenie]

Whoops, wasn't watching my own repository, so I missed this. What do you think of the readme in #10?

Having it in godoc in grohl.go is my preferred choice.

If godoc to markdown works well enough, we could just add something in script/* to handle it. That script can depend on godocdown without grohl needing to.

[technoweenie]

Now that I think about it, the README and godoc comments have slightly different purposes. Is it possible and desirable to break the README up into godoc comments in individual files? I like the idea of the README staying a full walkthrough though.

[simeonwillbanks]

No worries!

Regarding README and godoc comments having slightly different purposes, agreed. Looking at other libraries, I like the goworker README and the go-github README. Those READMEs aren't exact copies of their libraries' godoc, and they include Build Status, Installation, Getting Started/Usage, etc.

Regarding individual file comments, we can write those comments using godoc in the files, and they'll show up on godoc.org.

For reference, here are my experimental commits:

• ./script/readme
• Generated README

I think the godocs look better.

[technoweenie]

Thanks for your feedback!

[simeonwillbanks]

You're Welcome!

Just starting a pat app, and I'm using Grohl for logging. 😄

Do you prefer a framework or built-in net/http?

[technoweenie]

I love net/http (especially how pat or gorilla/mux integrate with them). But I'm also inadvertently hobbling a web framework together. I don't know if I'll ever release it, or try and make it some fancy framework. What I have now is more of a rough pattern.

[simeonwillbanks]

Thanks for the info and sounds fun. Good luck!