Go Concepts - Documentation: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(19 intermediate revisions by the same user not shown)
Line 1: Line 1:
=Internal=
=Overview=
 
* [[Go Concepts#Subjects|Concepts]]
* <tt>[[Go Commands - doc|go doc]]</tt>


=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.


Go generates in-line documentation for symbols in packages, 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.


=Reading Documentation=
=Reading Documentation=
Line 13: Line 10:


<pre>
<pre>
go doc <package-path>
go doc <package-name>
go doc <package-name>
</pre>
where the <tt>package-path</tt> is the same string literal used in the [[Go Keyword import#Overview|import statement]].
Example:
<pre>
go doc fmt
go doc project1/blue
</pre>
</pre>


Line 19: Line 26:


<pre>
<pre>
go doc <package-name> <identifier>
go doc <package-path> <identifier>
</pre>
</pre>


=Package=
Example:


<pre>
<pre>
go doc <package>
go doc fmt Println
go doc project1/blue Blue
</pre>
</pre>


=Function=
=Writing Documentation=
 
==Package-Level Documentation==
 
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>
<pre>
go doc <package> <function-name>
/*
  ...
  ...
*/
pakcage mypackage
</pre>
</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==
Add a "//" comment before the exported identifier (package, function, type and global variable).


Example:
Example:


<pre>
<pre>
go doc fmt Println
// This function pains all its arguments blue
fun Blue(s string) string {
...
}
</pre>
 
<tt>go doc</tt> will work as follows:
 
<pre>
go doc blue Blue
func Blue(s string) string
    This function paints all its arguments blue
</pre>
</pre>


=Local Web Site=


<pre>
godoc -http=":8088"
</pre>


=Writing Documentation=
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