{"id":18712243,"url":"https://github.com/amalmadhu06/godoc-example","last_synced_at":"2026-04-09T14:52:19.546Z","repository":{"id":165255989,"uuid":"640528894","full_name":"amalmadhu06/godoc-example","owner":"amalmadhu06","description":"How to use godoc for documenting your Go packages? Explained with examples","archived":false,"fork":false,"pushed_at":"2023-07-30T17:40:15.000Z","size":252,"stargazers_count":23,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-26T06:34:37.704Z","etag":null,"topics":["doc","documentation","documentation-generator","go","godoc"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amalmadhu06.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-14T11:55:04.000Z","updated_at":"2025-02-25T12:33:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"68f817d1-8078-4887-9d8b-d6a9c00be7f4","html_url":"https://github.com/amalmadhu06/godoc-example","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amalmadhu06%2Fgodoc-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amalmadhu06%2Fgodoc-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amalmadhu06%2Fgodoc-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amalmadhu06%2Fgodoc-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amalmadhu06","download_url":"https://codeload.github.com/amalmadhu06/godoc-example/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248565046,"owners_count":21125414,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["doc","documentation","documentation-generator","go","godoc"],"created_at":"2024-11-07T12:41:52.577Z","updated_at":"2026-04-09T14:52:14.504Z","avatar_url":"https://github.com/amalmadhu06.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# How to use godoc to generate documentation?\n**godoc** is a documentation tool for Go programming language that automatically generates documentation from code comments. Its three advantages are:\n1. Easy Accessibility: GoDoc provides a web-based interface that allows easy access to package documentation.\n2. Self-Contained Documentation: Documentation is generated directly from code comments, ensuring that it stays up-to-date and remains in sync with the codebase.\n3. Integration with Go Ecosystem: GoDoc integrates seamlessly with the Go ecosystem, making it a standard tool for developers to document and share their packages.\n\n## Install godoc\n1. Ensure that you have Go installed on your system. If not, download and install it from the official Go website (https://golang.org).\n2. Open your terminal or command prompt.\n3. Use the following command to install GoDoc\n```shell\ngo install golang.org/x/tools/cmd/godoc@latest\n```\nThis command will download and install the GoDoc tool and its dependencies.\n4. Wait for the installation to complete. GoDoc will be installed in your Go bin directory.\n5. Verify the installation by running the following command:\n```shell\ngodoc -h\n```\nIf GoDoc is successfully installed, you should see the help information for the GoDoc command.\n\n## Writing documentation\n\ngodoc uses comments for generating documentation.\n\nLet's create a new project and see how can we write documentation using godoc\n\n### Setup Project structure\n1. Create a new directory \n```shell\nmkdir godoc-example\ncd godoc-example\n```\n2. Initialize go module \n```shell\ngo mod init godoc-example\n```\n3. Create a new package `area` and two files inside it `area.go` and `shapes.go`. This package will define different geometrical shapes and methods for calculating their area\n```shell\nmkdir area\ntouch area/area.go\ntouch area/shapes.go\n```\n### Synopsis and overview\nSynopsis is a concise summary of our package. Following is the format of adding a synopsis\n```go\n// Package area provides functions for calculating the area of various shapes.\npackage area\n```\nOverview is added below this.\n```go\n// Package area provides functions for calculating the area of various shapes.\n//\n// This package includes functions to calculate the area of the following shapes:\n//   - Square\n//   - Rectangle\n//   - Circle\n//   - Triangle\n//   - Trapezoid\n//   - Parallelogram\n//   - Rhombus\n//   - Regular Pentagon\n//   - Regular Hexagon\npackage area\n```\n\nAdd the above code to the `area.go` file.\nIf `shapes.go` file is showing any error (because of it's empty), just add the package declaration inside it\n```go\npackage area\n```\n\nNow let's see if our documentation is working as expected.\n1. Open terminal \n2. Use the following command to start the documentation server\n```shell\ngodoc -http :8080\n```\n3. Open any browser and visit \n`http://localhost:8080/` \u003cbr\u003e\nYou will be seeing this screen\n\u003cimg src=\"images/stdlib.png\"\u003e\nAs you can see, these are the standard libraries that Go provides. Click on the Standard library header to close it. \n4. Now you will be able to see this screen\n\u003cimg src=\"images/area-synop.png\"\u003e\nYou can already see the synopsis that we gave to our package.\n5. Click on `area`.\nIt will bring us to this page\n\u003cimg src=\"images/overview.png\"\u003e\nSo, both synopsis and overview is working as we expected.s\n\n## Documentation for types and functions\nNow we know how to add synopsis and overview for our package. Now let's define structs and method for calculating area of shapes. \n1. Define `Square` in `shapes.go` file\n```go\npackage area\n\n// Square represents a square shape.\ntype Square struct {\n\tSide float64 // Length of the side of the square\n}\n```\n2. Add a method `Area` in `area.go` file which calculates the area of the square\n   (inside `area.go`)\n```go\n// Area calculates the area of a square.\nfunc(s Square) Area() float64 {\n\treturn s.Side * s.Side\n}\n```\n3. Save the files, stop the document server and rerun it. Visit `http://localhost:8080/`\n4. You will be able to see the type and method we have defined, and it's documentation.\n\n## Add examples\nOne another powerful feature that godoc gives us is `examples`. Let's see how can we add example for `Area` method on struct `Square`\n\n1. Create a new file, `area_test.go` inside `area` directory\n2. Add following lines of code to the file\n```go\npackage area_test\n\nimport (\n\t\"fmt\"\n\t\"github.com/amalmadhu06/godoc-example/area\"\n)\n\nfunc ExampleSquare_Area() {\n\ts := area.Square{Side: 10}\n\tfmt.Println(s.Area())\n\t// Output:\n\t// 100\n}\n```\nThis is a test file. It helps to add examples also.\nYou can run this by using the command \n```shell\ncd area\ngo test -run ExampleSquare_Area\n```\nIf your test passes successfully, it will show, `PASS`, otherwise it will show what went wrong\n\nNow, stop the document server and run it again. Visit `http://localhost:8080/` and check inside area package.\nYou should see following there.\n\u003cimg src=\"images/square.png\"\u003e\n\n## Add more types and function. \nNow try to add more shapes in `shapes.go` and methods to calculate their area in `area.go`. Write meaningful comments and generate documentation with it. Don't forget to add examples for each method.  ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famalmadhu06%2Fgodoc-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famalmadhu06%2Fgodoc-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famalmadhu06%2Fgodoc-example/lists"}