Struct Field Comments

How Struct Field Descriptions Work

To be able to read struct field descriptions and use them in the GUI as tooltips, they need to be specified as struct field tags; for example:

type MyStruct struct {
    Field int `desc:"a description"`
}

This has the unfortunate side effect that struct field descriptions are not comments and thus can not be read by editor tools, like the VS Code Go extension. Being able to hover over a field and see its documentation in the editor is incredibly helpful, and it is critical for a good developer experience. As such, we came up with a solution for struct field description comments: a fork of goimports.

The goki/go-tools repository

The goki/go-tools repository is a fork of golang/tools, and it modifies goimports to automatically insert documentation comments for struct fields based on their description tags and other tags. For example, it would change the example struct above to the following:

type MyStruct struct {
    // a description
    Field int `desc:"a description"`
}

We build upon goimports because it is a tool already called in almost all Go editors on save, so it will easily keep struct field comments up to date with no worrying about go generate commands. Any time you add, update, or remove the description for a struct field, the comment will update immediately on save. Also, any changes to the comment will be reverted.

Installation

The struct field comments generated by the tool will be visible in all editors without any extra effort. However, if you are making an app with Goki that uses struct field descriptions or contributing to any of the Goki repositories, you should install the fork of goimports so that you will generate struct field comments. Installation is very simple – you just have to run

go install github.com/goki/go-tools/cmd/goimports@latest

Then, you should configure your editor to run the correct version of goimports. For our Gide editor, there is no more configuration necessary. For VS Code, you should follow these steps:

1. Run which goimports and copy the result, as you will need it later.
   • On Windows, run where goimports in Command Prompt (not Git Bash like other commands) instead.
2. Go to Settings and search for goimports
3. Set Go: Format Tool to custom
4. In the description for Go: Format Tool, click on Go: Alternate Tools
5. Click Edit in settings.json
6. Add a new line under "go.alternateTools": { that says "customFormatter": "{{THE_RESULT_OF_WHICH_GOIMPORTS_THAT_YOU_COPIED}}" (obviously substituting in the thing you copied earlier)
   • On Windows, you need to run change the result of where goimports that you pasted in by adding an extra backslash to each backslash (for example, C:\Users\me\go\bin\goimports.exe would change to C:\\Users\\me\\go\\bin\\goimports)

After you do those steps, the go section of your settings.json should contain the following lines:

"go.formatTool": "custom",
"go.alternateTools": {
    "customFormatter": "{{THE_RESULT_OF_WHICH_GOIMPORTS_THAT_YOU_COPIED}}"
},

For other editors, you should be able to figure out what to do by doing something similar to the steps for VS Code above, looking at the goimports installation directions, and looking for settings related to goimports and Go tools. If you are unable to figure out how to configure your editor to run the correct goimports tool, please create an issue on the goki/go-tools repository.