search

lucdoe / opengateway

API Gateway written in Go for small to mid-sized projects. Easy setup, extendable with plugins, and fully customisable.
Apache License 2.0
5 stars 0 forks source link

Research: into how to best document Go codebases #31

Open lucdoe opened 1 month ago

lucdoe commented 2 weeks ago

According to https://go.dev/doc/comment:

"Doc comments are comments that appear immediately before top-level package, const, func, type, and var declarations with no intervening newlines."

lucdoe commented 2 weeks ago

"The square brackets in [path/filepath] create a [documentation link]."

For commands:

"first sentence conventionally begins with the name of the program"

"For a struct with exported fields, either the doc comment or per-field comments should explain the meaning of each exported field"

"Doc comments typically use the phrase “reports whether” to describe functions that return a boolean"