go.dev is a site where various resources for Go developers are shared, such as “Get Started”, Tutorial, Packages (pkg.go.dev), and all the official blogs. Among them, Packages is where I visit most, which allows free access to all the open-source Go packages submitted by communities including the native Golang packages. Thanks to all the contributors, I enjoy the great benefit, and sometimes I want to be a contributor myself.

Let’s submit a “complete” package to pkg.go.dev today.

Came pkg.go.dev into being

Before pkg.go.dev’s birth in 2019, packages were managed under godoc.org , and its releases were managed by godoc command. And then the latest pkgsite was introduced to provide a single source for packages and modules. Upon the accomplishment of migration in 2021, all the packages and modules were published under pkg.go.dev, and godoc.org became a history.

Publish a package

Only three steps to go according to the official documentation.

* Visiting that page on pkg.go.dev, and clicking the “Request” button. For example: https://pkg.go.dev/example.com/my/module

* Making a request to proxy.golang.org for the module version, to any endpoint specified by the Module proxy protocol. For example: https://proxy.golang.org/example.com/my/module/@v/v1.0.0.info

* Downloading the package via the go command. For example:
GOPROXY=https://proxy.golang.org GO111MODULE=on go get example.com/my/module@v1.0.0

— from https://pkg.go.dev/about#adding-a-package

Test with the localcache package I created before, and try to open github.com/slaise/go_localcache — pkg.go.dev. Oops！

Click the request and sit back. My package page will only be available after 24 hours! ( what I observed!)

Keep in mind that the package must contain a validated go.mod file to import correctly. And most importantly, the module declaration format in go.mod must conform to the specification here.

Otherwise, the following error will occur.

pkg documentation

What a pkg page should offer

Read it through, you’ll find the pkg page is far different from others, for instance, the pkg page in the bigcache below contains the version number, all the checks it passes, and a fine-defined README doc, and all the flags.

Under Documentation, you can find docs for all types, functions, constants, and errors. And something better? Foldable code examples!

The bigcache pkg page shows us where to target our efforts when working on an open-source project, while localcache is just a simple “scaffolding” project, which still has a long way to go in optimizing its pkg page.

In general, a beautiful pkg page should contain

A complete README page with more project information.
A complete documentation section, in which lies your API documentation, just like the JDK’s API documentation, is a window for others to use your public API.
Source Files, a link refers to the source code.
Directories, the subdirectories list of the current package.

Among the four, the first and second bullet points are vital.

A well-written README should at least cover the project introduction, implementation principles, guidelines, and precautions for installation and usage.

Documentation comes from the code and shows godoc’s powerfulness. It is no big deal to generate a perfect pkg doc as long as you follow the comments syntax. It always includes Overview, Index, Functions and Types to make users understand package usage and some exposed implementation logic.

Build the documentation

Now let’s add the documentation.

Godoc parses Go source code — including comments — and produces documentation as HTML or plain text.

Tools like pkg.dev.go and pkgsite will automatically generate web content in pkg based on code comments.

Understand the syntax

Godoc mainly parses comments in the following syntaxes, obtaining different HTML patterns.

The // and /* */ formats. The definition of the comments is the same as in Java and supports both the // and /* */ formats. // is for short Type or Method documentation, and most IDEs support the short key of Commod + / to quickly add and cancel // comments. While, for those long comments with code and bullet lists, /**/ is more adequate.

Only comments on top of the type that requires documentation can function(not applicable if there is a blank line in between), e.g.

// Const DEFAULT_EXPIRATION gives the default ttl time period for all keys
DEFAULT_EXPIRATION = 10 * time.Minute

// Const DEFAULT_CLEAN_DURATION(This won’t show in the doc because of the extra empty line)
DEFAULT_CLEAN_DURATION = 10 * time.Minute

Line breaker. A blank line is needed between the two lines.

// Elem defines the item of the Cache value.
// It contains K as Key, V as value, Expiration and LastHit
type Elem struct {}
  
// RemoveExpired triggers the a clean for expired keys
// 
// It is thread-safe.
func (c *Cache) RemoveExpired() {

In Elem and RemoveExpired, only the RemoveExpired doc has two lines.

Deprecated. For methods or types that have been deprecated, just add Deprecated: at the beginning of comments.
Code example. To add code in doc, start the comment line with\t or with more than one space, e.g.

/* Package localcache provides an in-memory and thread-safe cache storageExample
   cache, _ := NewCache()
   cache.Put("a", 1)
   a, _ := cache.Get("a")*/

Displayed as

There are also several relatively high-level applications.

Package comments. The Overview part you see in pkg is the comments I added. Package doc can load all the go files defined by this package, and display them in alphabetical order if there is more than one. For those lengthy package comments, a more common way is to write by a doc.go, as is done in this jwt.
The foldable Examples in Overview, what we have seen in the bigcache pkg. It is implemented by an independent example_test.go, and this go package must be different from the original package. And the similar effect can be achieved by rewriting the Package doc in localcache.

Now we can start polishing our code to make the pkg page more user-friendly. And you can refer to doc.go for comments format from the official recommendation.

Test it locally

pkg didn’t pass my pkg request after I finished adding all the documentation locally. A long wait.

But pkgsite supports local test so that I can test my doc in time without waiting for pkg’s time-consuming refresh.

# need to run under go1.18
go install golang.org/x/pkgsite/cmd/pkgsite@latest

Start a local UI.

# default 8080 port
pkgsite# or customize the port
pkgsize -http=:9090

See in the browser.

About removal

To hide the version in pkg after its release, you can add retract to the go.mod file. Learn more about retract here.

To remove the entire package, you need to submit a request here.

With all this knowledge in mind, you can then take an attempt when you are ready to publish your own go package.

Thanks for reading!

Reference

Note: The post is authorized by original author to republish on our site. Original author is Stefanie Lai who is currently a Spotify engineer and lives in Stockholm, original post is published here .