Go Concepts - Documentation: Difference between revisions
(7 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
= | =Overview= | ||
Go generates in-line documentation for symbols in packages, for the standard library and for custom code, as long as it is referred to from GOPATH, via the <tt>go doc</tt> command. | |||
The Go documentation uses the term ''command'' frequently to refer to an executable program - as in ''command''-line application. | |||
Go | |||
=Reading Documentation= | =Reading Documentation= | ||
Line 14: | Line 11: | ||
<pre> | <pre> | ||
go doc <package-path> | go doc <package-path> | ||
go doc <package-name> | |||
</pre> | </pre> | ||
Line 42: | Line 40: | ||
==Package-Level Documentation== | ==Package-Level Documentation== | ||
<font color=red>'''TODO'''</font> | To add a large body of text to document a package, include a file called <tt>doc.go</tt> in the package directory. Place the package documentation as a comment before the package declaration: | ||
<pre> | |||
/* | |||
... | |||
... | |||
*/ | |||
pakcage mypackage | |||
</pre> | |||
This documentation will be shown before any type or function documentation is displayed for the package. | |||
<font color=red>'''TODO''' not testes. Test and annotate.</font> | |||
==Package Identifier Documentation== | ==Package Identifier Documentation== | ||
Add a "//" comment before the exported identifier (function, type | Add a "//" comment before the exported identifier (package, function, type and global variable). | ||
Example: | Example: | ||
Line 70: | Line 80: | ||
godoc -http=":8088" | godoc -http=":8088" | ||
</pre> | </pre> | ||
The documentation is available at http://localhost:8088/pkg |
Latest revision as of 22:51, 26 September 2023
Overview
Go generates in-line documentation for symbols in packages, for the standard library and for custom code, as long as it is referred to from GOPATH, via the go doc command.
The Go documentation uses the term command frequently to refer to an executable program - as in command-line application.
Reading Documentation
To read the package summary:
go doc <package-path> go doc <package-name>
where the package-path is the same string literal used in the import statement.
Example:
go doc fmt go doc project1/blue
To get the documentation for a package identifier (function name, type, etc):
go doc <package-path> <identifier>
Example:
go doc fmt Println go doc project1/blue Blue
Writing Documentation
Package-Level Documentation
To add a large body of text to document a package, include a file called doc.go in the package directory. Place the package documentation as a comment before the package declaration:
/* ... ... */ pakcage mypackage
This documentation will be shown before any type or function documentation is displayed for the package.
TODO not testes. Test and annotate.
Package Identifier Documentation
Add a "//" comment before the exported identifier (package, function, type and global variable).
Example:
// This function pains all its arguments blue fun Blue(s string) string { ... }
go doc will work as follows:
go doc blue Blue func Blue(s string) string This function paints all its arguments blue
Local Web Site
godoc -http=":8088"
The documentation is available at http://localhost:8088/pkg