As you know if you read my blog, I have been building a set of new utility packages so I can start developing an application server I need for a new project. I am brand new to Go and the Mac OS. Needless to say it has been one hell of an education over the past month. But I don’t miss Windows or C# at all.
I made some progress in my coding and wanted to build documentation for the code. I have been using the documentation viewer in LiteIDE and I was hoping to integrate my documentation in there was well. I was really surprised to see see that LiteIDE already had my packages listed inside of their integrated Godoc viewer. So it then begged the question. How is that working?
After some digging around I found this local HTML file. If you have LiteIDE installed you can copy the following url into your browser.
file:///Applications/LiteIDE.app/Contents/Resources/golangdoc/about.html
This is what it shows
Overview
The integrated Godoc viewer in LiteIDE provides an easy way to browse documentation generated by the godoc tool without leaving the editor. Documentation can be viewed for both the official Go language as well as custom packages. The remainder of this page describes ways to invoke the Godoc viewer.
Supported URL Schemes
It is possible to view documentation by directly entering a URL into the Godoc viewer's address bar. When doing this, you can specify what type of documentation you are looking for by prefixing the address with one of the following URL schemes:
find
Searches for packages with a specified string in their name. For example:
list
Lists all packages in a given directory. The main choices are "pkg" and "cmd", which can be found as links in the header of the page. For example:
pdoc
Views documentation for a specified package or command. For example:
file
Views a specified HTML, Markdown, or plain-text file. For example:
Automatic Schemes
For the "file" and "pdoc" schemes, you do not need to type the scheme as part of the URL. For example:
- [/doc/code.html](/broken-link)
- [/src/pkg](/broken-link)
- [/src/cmd](/broken-link)
- [/pkg/fmt](/broken-link)
- [/cmd/cgo](/broken-link)
- [archive/zip](/broken-link)
- [Go](/broken-link)
File Browser
You can open the Godoc viewer directly from the file browser by right clicking on a file or directory and selecting "View Godoc Here". The Godoc viewer will automatically open the package documentation for the chosen item.
When I clicked on my package
ArdanStudios/threadpool from within the LiteIDE Godoc search tool it used the pdoc URL scheme,
pdoc:ArdanStudios/threadpool.I quickly reasoned that LiteIDE was using the GOROOT and GOPATH variables to find the documentation. There is only one problem, I haven't created any documentation yet.
So I looked around in both
/usr/local/go and my own space to find the documentation files and there was nothing. So how the heck was this documentation being generated and published on the screen?
Then I found this document from the Go team:
http://golang.org/cmd/godoc/The very first line states, "
Godoc extracts and generates documentation for Go programs." Ok, so this program is being used by LiteIDE but how? Where are the files that Godoc is generating for all this documentation?
LOL, boy it is difficult coming from a Windows environment for the past 20 years.
After reading the documentation a bunch of times I opened up a Terminal session and ran the following command.
godoc /Users/bill/Spaces/GoPackages/src/ArdanStudios/threadpoolSuddenly the documentation appeared on my screen in text format. But I am seeing HTML inside of LiteIDE? I found the
-html option.
godoc -html /Users/bill/Spaces/GoPackages/src/ArdanStudios/threadpool
Now I produced the same documentation I am seeing inside of LiteIDE. There are no extra files on my machine, LiteIDE is streaming the output of Godoc directly into the screen. Very smart way of doing things!!
So if I can see documentation for the standard Go packages, then the source code for those packages must be on my machine. After a bit of looking I found them in:
/usr/local/go/src/pkg
It seems they are located inside a folder called
pkg under
src. This is because the Go team likes to put source code for reusable libraries within a project under
pkg. Not all developers follow that same convention and you have the freedom to choose. I personally don't follow that convention. Apparently the Godoc tool has no problems finding the source code files.
Godoc tool is always reading the source code files to produce the latest version of the documentation. So in LiteIDE when you update your documentation and save the code file, the Godoc tool will show the changes immediately.
Now the next problem I have, my documentation looks really bad. The documentation that I see from the standard library files looks much better. So how do I format my documentation properly inside the Go code files?
I found this document from the Go team:
http://golang.org/doc/articles/godoc_documenting_go_code.htmlThe introduction reads:
Godoc: documenting Go code
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.
To that end, we have developed the godoc 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.
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 documentation to its implementation with one click.Coming from the C# world and using XML tags like <summary> for that past 10 years and having to remember to check the "produce XML documentation file" option, this was a dream. Oh yea, no extra documentation file.
However the rest of the page was lacking. I liked the way the documentation for fmt.Printf looked so I quickly found the go source files and studied what the programmer did. After a bit of playing I finally figured out the 3 basic rules you need to help the Godoc tool format the documentation cleanly.
Here is a sample of the documentation I have for my tracelog package:
There are 3 elements in play when writing your documentation. You have header sections, standard text and highlighted text.
At the very top of your code file add the following using the // comment operation or something similar. Obviously you want to give yourself the credit for your work, LOL.
// Copyright 2022 Ardan Studios. All rights reserved.// Use of this source code is governed by a BSD-style// license that can be found in the LICENSE file.Then add a block comment operator and we can start. Make sure the
package code statement is exactly after the closing comment operator. There can not be no blank lines between the two.
Tabbing is very important. We are using two layers of tabbing. Keep these two layers of tabbing consistent.
/*
->TAB Package TraceLog implements a file based logging.
->TAB The programmer should feel free to tace log as much of the code.
->CRLF
->TAB New Parameters
->CRLF
->TAB The following is a list of parameters for creating a TraceLog:
->TAB baseFilePath: The base location to store all log directories.
->TAB machineName: The name of the machine or system. Information is used.
->TAB writeToStdout: Set to True if you want the system to also write.
->CRLF
->TAB TraceLog File Management
->CRLF
->TAB Every 2 minutes TraceLog will check each open file for two conditions:
->CRLF
->TAB 1. Has a message been written to the file within the last 2 minutes.
->TAB 2. Is the size of the file greater than 10 Meg.
*/
package tracelog
The first section of comments will show at the top of our documentation just below the Overview Section. Also the first sentence will appear in Godoc's package list.
Then we have a blank line and a string that will become a header as long as the next line is double spaced and has the same indentation.
The final component is the second tabbing indentation. This will cause that text to be highlighted with a grey background.
You may need to remove all of your existing documentation from your Go code file and throw it into a text editor. Then put it back in to make sure all the tabs and carriage returns are clean.
Using GoDoc.orgIf you are building a public package you can use the GoDoc website to publish your documentation. Check out the GoDoc website:
[http://godoc.org/] (http://godoc.org/)
This website has been setup to read your code files and display all of your great documentation. Enter this url (github.com/goinggo/utilities/v1/workpool) into the search box and see the documentation that GoDoc produces for my workpool package:
You can see the same documentation that is being given to you locally is now published on the GoDoc website with your own reuseable url:
So how can you best use this url to provide people your documentation? When you create a repository for your package add a README.md file. This is a special "Markdown" file that supports standard text, html and a few special operators of its own. Github has its own extensions and you can find documentation about Markdown here:
https://help.github.com/articles/github-flavored-markdownIf you happened to come across my public workpool package in Github, you would see the following:
There is my code file, license file and my readme Markdown file.
Here is a typical README Markdown file that I use:
# Workpool - Version 1.0.0
Copyright 2022 Ardan Studios. All rights reserved.<br />
Use of this source code is governed by a BSD-style license that can be found in the LICENSE handle.
Ardan Studios<br />
12973 SW 112 ST, Suite 153<br />
Miami, FL 33186<br />
bill@ardanstudios.com<br />
[Click To View Documentation](/broken-link)
View The Raw Version Here:
[https://raw.github.com/goinggo/utilities/master/v1/workpool/README.md](/broken-link)
Look at the Markdown link at the bottom of the file. This syntax creates a link to the documentation. The text in the hard brackets [], provides the anchor text for the link.
Since Github always display the Readme Markdown file to the user if one exists, this is what people see when they come to that Github page:
Now people have access to the documentation I write on the web as well. I don't need to copy and paste the documentation into the Readme Markdown file, just provide a link. All the documentation is in one place and formatted cleanly and consistently.
As always, I hope this helps you in some small way and your documentation draws people to your work.