1 files changed, 139 insertions, 0 deletions
diff --git a/doc/articles/godoc_documenting_go_code.html b/doc/articles/godoc_documenting_go_code.html
new file mode 100644
index 000000000..ca66076ad
--- /dev/null
+++ b/doc/articles/godoc_documenting_go_code.html
@@ -0,0 +1,139 @@
+<!--{
+"Title": "Godoc: documenting Go code",
+"Template": true
+}-->
+
+<p>
+The Go project takes documentation seriously. Documentation is a huge part of
+making software accessible and maintainable. Of course it must be well-written
+and accurate, but it also must be easy to write and to maintain. Ideally, it
+should be coupled to the code itself so the documentation evolves along with the
+code. The easier it is for programmers to produce good documentation, the better
+for everyone.
+</p>
+
+<p>
+To that end, we have developed the <a href="/cmd/godoc/">godoc</a> documentation
+tool. This article describes godoc's approach to documentation, and explains how
+you can use our conventions and tools to write good documentation for your own
+projects.
+</p>
+
+<p>
+Godoc parses Go source code - including comments - and produces documentation as
+HTML or plain text. The end result is documentation tightly coupled with the
+code it documents. For example, through godoc's web interface you can navigate
+from a function's <a href="/pkg/strings/#HasPrefix">documentation</a> to its
+<a href="/src/pkg/strings/strings.go?#L312">implementation</a> with one click.
+</p>
+
+<p>
+Godoc is conceptually related to Python's
+<a href="http://www.python.org/dev/peps/pep-0257/">Docstring</a> and Java's
+<a href="http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html">Javadoc</a>,
+but its design is simpler. The comments read by godoc are not language
+constructs (as with Docstring) nor must they have their own machine-readable
+syntax (as with Javadoc). Godoc comments are just good comments, the sort you
+would want to read even if godoc didn't exist.
+</p>
+
+<p>
+The convention is simple: to document a type, variable, constant, function, or
+even a package, write a regular comment directly preceding its declaration, with
+no intervening blank line. Godoc will then present that comment as text
+alongside the item it documents. For example, this is the documentation for the
+<code>fmt</code> package's <a href="/pkg/fmt/#Fprint"><code>Fprint</code></a>
+function:
+</p>
+
+{{code "/src/pkg/fmt/print.go" `/Fprint formats using the default/` `/func Fprint/`}}
+
+<p>
+Notice this comment is a complete sentence that begins with the name of the
+element it describes. This important convention allows us to generate
+documentation in a variety of formats, from plain text to HTML to UNIX man
+pages, and makes it read better when tools truncate it for brevity, such as when
+they extract the first line or sentence.
+</p>
+
+<p>
+Comments on package declarations should provide general package documentation.
+These comments can be short, like the <a href="/pkg/sort/"><code>sort</code></a>
+package's brief description:
+</p>
+
+{{code "/src/pkg/sort/sort.go" `/Package sort provides/` `/package sort/`}}
+
+<p>
+They can also be detailed like the <a href="/pkg/encoding/gob/">gob package</a>'s
+overview. That package uses another convention for packages
+that need large amounts of introductory documentation: the package comment is
+placed in its own file, <a href="/src/pkg/encoding/gob/doc.go">doc.go</a>, which
+contains only those comments and a package clause.
+</p>
+
+<p>
+When writing package comments of any size, keep in mind that their first
+sentence will appear in godoc's <a href="/pkg/">package list</a>.
+</p>
+
+<p>
+Comments that are not adjacent to a top-level declaration are omitted from
+godoc's output, with one notable exception. Top-level comments that begin with
+the word <code>"BUG(who)”</code> are recognized as known bugs, and included in
+the "Bugs” section of the package documentation. The "who” part should be the
+user name of someone who could provide more information. For example, this is a
+known issue from the <a href="/pkg/bytes/#bugs">bytes package</a>:
+</p>
+
+<pre>
+// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.
+</pre>
+
+<p>
+Godoc treats executable commands somewhat differently. Instead of inspecting the
+command source code, it looks for a Go source file belonging to the special
+package "documentation”. The comment on the "package documentation” clause is
+used as the command's documentation. For example, see the
+<a href="/cmd/godoc/">godoc documentation</a> and its corresponding
+<a href="/src/cmd/godoc/doc.go">doc.go</a> file.
+</p>
+
+<p>
+There are a few formatting rules that Godoc uses when converting comments to
+HTML:
+</p>
+
+<ul>
+<li>
+Subsequent lines of text are considered part of the same paragraph; you must
+leave a blank line to separate paragraphs.
+</li>
+<li>
+Pre-formatted text must be indented relative to the surrounding comment text
+(see gob's <a href="/src/pkg/encoding/gob/doc.go">doc.go</a> for an example).
+</li>
+<li>
+URLs will be converted to HTML links; no special markup is necessary.
+</li>
+</ul>
+
+<p>
+Note that none of these rules requires you to do anything out of the ordinary.
+</p>
+
+<p>
+In fact, the best thing about godoc's minimal approach is how easy it is to use.
+As a result, a lot of Go code, including all of the standard library, already
+follows the conventions.
+</p>
+
+<p>
+Your own code can present good documentation just by having comments as
+described above. Any Go packages installed inside <code>$GOROOT/src/pkg</code>
+and any <code>GOPATH</code> work spaces will already be accessible via godoc's
+command-line and HTTP interfaces, and you can specify additional paths for
+indexing via the <code>-path</code> flag or just by running <code>"godoc ."</code>
+in the source directory. See the <a href="/cmd/godoc/">godoc documentation</a>
+for more details.
+</p>