internal/docsite/code.go
internal/docsite · 646 lines · 31 declarations · source
Declarations
const module
const module = "github.com/ensera-ai/taisce/"
module is the import path prefix that marks a package as this repository's own.
type goPackage
type goPackage struct {
Dir, Name, Doc string
Files []goFile
Tests []goTest
Imports []string
ImportedBy []string
Data []string
symbols map[string]string // symbol → anchor, for doc links
}
type goFile
type goFile struct {
Name, Doc, Constraint string
Lines int
CarriesPackageDoc bool
Decls []goDecl
}
type goDecl
type goDecl struct {
Kind, Name, ID, Code, Doc string
Line int
}
type goTest
type goTest struct {
File, Name, Doc string
Line int
}
func loadPackages
func loadPackages(root string) ([]goPackage, error)
loadPackages finds every Go package under cmd/ and internal/ and reads it. A package with no doc comment is refused: that comment is where a package says what it may decide and what it must not, and nothing else in the code says so.
func loadPackage
func loadPackage(root, dir string) (goPackage, bool, error)
loadPackage reads one directory. ok is false when it holds no non-test Go file.
func dataFiles
func dataFiles(root, dir, sub string) []string
dataFiles lists the non-Go files a package carries in a subdirectory that is not itself a package: embedded migrations, templates, prompts. Test fixtures are not part of what the package is.
func packageDoc
func packageDoc(f *ast.File) string
packageDoc is a file's package documentation. The parser takes whatever comment sits directly on the package clause, and in a file with no documentation of its own that is the licence header; it is stripped, so a header is never mistaken for a package saying what it is for.
func readFile
func readFile(fset *token.FileSet, f *ast.File, name string, src []byte) goFile
func receiverName
func receiverName(expr ast.Expr) string
func printNode
func printNode(fset *token.FileSet, f *ast.File, node ast.Node) string
printNode prints a declaration with the comments inside it, which for a struct are the field documentation and for a const block are the reasons each value is what it is.
func readTests
func readTests(fset *token.FileSet, f *ast.File, name string) []goTest
readTests lists the tests in one file. The names state the properties the tests hold (rule 6), which makes them the most precise description of behaviour the repository has.
func isTestName
func isTestName(name string) bool
func humanize
func humanize(name string) string
humanize turns a test name back into the sentence it was written from: TestATurnThatWillNotFormIsParked becomes "A turn that will not form is parked".
func splitWords
func splitWords(s string) []string
func firstSentence
func firstSentence(text string) string
type rendered
type rendered struct {
pages []page
nav string
count int
}
func packagePage
func packagePage(dir string) string
func fileStage
func fileStage(dir, file string) string
fileStage names a file's page after the file with its dot spelt as a hyphen: api.go is api-go.md. Dropping the extension instead would give api/api.md, which the renderer takes to be the index of the api directory and so the same address as the package page.
func renderCode
func renderCode(packages []goPackage, opts Options) rendered
func codeIndex
func codeIndex(packages []goPackage) string
func nodeID
func nodeID(dir string) string
func packageBody
func packageBody(p goPackage, opts Options) string
func packageList
func packageList(dirs []string, from string) string
func fileSummary
func fileSummary(f goFile) string
func fileBody
func fileBody(p goPackage, f goFile, packages []goPackage, opts Options) string
func testsBody
func testsBody(p goPackage, opts Options) string
func renderDoc
func renderDoc(text string, p goPackage, from string, level int) string
renderDoc renders a doc comment as markdown. A reference to a symbol of this package, or of another package in the repository, links to its declaration; a standard library reference links to its documentation; anything else stays text.
func cell
func cell(s string) string
cell makes text safe inside a table cell or a single list item.
func fenced
func fenced(code string) string
fenced keeps a code block from being closed early by a declaration that itself contains a fence.