Go doc is not picking up my doc comments in my multi cmd project

[wooden gale]

Hi all, I followed a simple tutorial to gin and added go doc comments to all my functions, here is e.g.

package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
)

// getAlbumByID locates the album whose ID value matches the id
// parameter sent by the client, then returns that album as a response.
// @Summary Get album by ID
// @Description get album by ID
// @Produce json
// @Param id path string true "Album ID"
// @Success 200 {object} album
// @Failure 404 {object} gin.H{"message": "album not found"}
// @Router /albums/{id} [get]
func getAlbumByID(c *gin.Context) {
 // impl details... 
}

However, when I run go doc .\cmd\gin it returns empty, and when I run godoc -http :8080 and navigate to my url of http://localhost:8080/pkg/toybox-go/cmd/gin/ it is also empty. This has been my experience for all my cmd folders so far. What's going on here?

my .mod file is in my toybox-go repo. I've been doing my best to follow best practices on this project, but not 100% sure if I'm doing things correctly as I'm a green gopher.

Here's my project tree setup:

C:.
├───.vscode
├───cmd
│   ├───client
│   ├───gin
│   └───server
├───githooks
├───node_modules
└───shared
    ├───models
    └───utils

[neon glen]

only exported functions show up - name it GetAlbumByID and it'll show up

[wooden gale]

I thought in go we were supposed to prefer Value to GetValue ?

oh you just mean the capital ***

@neon glen that actually didn't make a difference for me.

[neon glen]

I thought in go we were supposed to prefer Value to GetValue ?
yes that's true as well, I was just correcting/mentioning from the code above

well main package is also... let me check, not sure stuff in main gets godoc'ed

[wooden gale]

I tried moving my code into src and shared and that didnt help

[neon glen]

don't use src/

nor shared/

[wooden gale]

You're right. main isn't documented

[neon glen]

(later read https://laurentsv.com/blog/2024/10/19/no-nonsense-go-package-layout.html ) meanwhile yes godoc will be package level only for main, like https://pkg.go.dev/fortio.org/[email protected]/example has just the package doc not functions because functions in a main package can't be imported

[wooden gale]

Hm. so i wanted to have a client, a server, and another binary in my cmd folder, but if i want to document them, that means i'd need their own functionality to be external (because if i want them to be binaries they'd need to use the main package) right?

oh womp womp. i guess i was wrong about that assumption. I can have a file in cmd/client be part of the client package and still have a main method.

erf noooo that isn't true -- then it says main method is not used.

I guess I now understand the issue, but not sure how to proceed. Right now my main method is the entrypoint to my program and contains all the functoins relating to album. So i guess the fix would be to add a new go file albums.go in cmd/gin and import the package in my main?

[neon glen]

you can have multiple binaries using/sharing library code, that's not a problem

and you do want your main(s) to be minimal

usually just flag parsing / env reading and then calling the actual code which would have its own tests

[wooden gale]

it looks like my albums package can't be in the same folder as gin.go (package main) as well found packages albums (albums.go) and main (gin.go) in C:\Users\cphillips\Documents\Git\toybox-go\cmd\gin

[neon glen]

in go directories == packages - so you can't have in same directory a main package and a non main package

which is why if you have multiple binaries, it's common to shove them under cmd/binaryname1 cmd/binaryname2 etc

[wooden gale]

im starting to think multiple binaries is kind of an antipattern exception in Go, and not the norm?

[neon glen]

personally I skip the cmd/ but... still you have to decide what is your focus/what you put at the top level and the rest imports it (again the main(s) should be small and use the common code via import)

"it depends" it's fine if it make sense, a client and server or some demos/ or examples/ for a library is not an anti pattern

the "bug" in your layout I think is cmd/gin not sure what is there but if it's using the gin web framework it should just be at the top

[wooden gale]

Right now that file looks like this

package main

import (
    "toybox-go/albums"

    "github.com/gin-gonic/gin"
)

// @title Album API
// @version 1.0
// @description This is a simple API to manage albums.
// @host localhost:8080
// @BasePath /
func main() {
    router := gin.Default()
    router.GET("/albums", albums.GetAlbums)        // Get all albums
    router.GET("/albums/:id", albums.GetAlbumByID) // Get album by ID
    router.POST("/albums", albums.PostAlbums)      // Create a new album

    router.Run("localhost:8080")
}

[neon glen]

and see my blog post above for why you don't want to call a package utils/ and why shared/ is also weird/bad

[wooden gale]

yeah i read thru it but ill read it again after our cnvo thanks so much

can you explain why you think it should be at the top? and what specifically do you mean by top? do you mean just a folder called gin instead of cmd/gin like your article says? or something else?

Right now I'm at least a little bit satisfied that my albums package is being documented, and I still get multi-binary goodness

yeah i see what you mean totally now i think. Thanks so much for the help.

[neon glen]

I mean that if you don't have a (solo/main) binary at the top then you would probably want to put some code at the top (in the top level directory, ie root of your repo, where go.mod is)

a package named after the library part ... though it's also ok it's all sub directories I guess

[wooden gale]

├───albums
├───myframework (imports albums)
├───client # simple tcp demo (package main)
├───gin-server (imports myframework) (package main)
├───server # simple tcp demo (package main)
├───go.mod

something like this is what you'd reccomend, right?

[neon glen]

why package main in gin-server vs server/

or are these unrelated servers a tcp vs http server? is the tcp one using albums?

[wooden gale]

yeah you're right. client and server came first and is a really simple tcp demo where the server spits back a message to the client
and gin-server is a web framework server.

Overall this is just a toy project for me to learn how to use go "the right way" in contrast to an existing project.
That's why it's named that way.

the contrasted example is also a collection of "binary microservices" so thats why i dont have a root main

only the gin-server is using albums. Maybe there would be an appropriate way to group client and server to gether in a way that makes them not mentally connected to the gin-server and album, but idk about that.

[sturdy zephyr]

Is this project in a public repository somewhere?

If so, I can go through it in the morning and give some feedback