refactor: rewrite comments to be prefixed with the subject name

cmd/osv-scanner/internal/helper/callanalysis_parser.go

@@ -5,7 +5,7 @@ var stableCallAnalysisStates = map[string]bool{
 	"rust": false,
 }
 
-// Creates a map to record if languages are enabled or disabled for call analysis.
+// CreateCallAnalysisStates creates a map to record if languages are enabled or disabled for call analysis
 func CreateCallAnalysisStates(enabledCallAnalysis []string, disabledCallAnalysis []string) map[string]bool {
 	callAnalysisStates := make(map[string]bool)
 

cmd/osv-scanner/internal/helper/helper.go

@@ -19,7 +19,8 @@ import (
 	"golang.org/x/term"
 )
 
-// flags that require network access and values to disable them.
+// OfflineFlags is a map of flags which require network access to operate,
+// with the values to set them to in order to disable them
 var OfflineFlags = map[string]string{
 	"include-git-root":                     "true",
 	"experimental-offline-vulnerabilities": "true",
@@ -131,7 +132,7 @@ var GlobalScanFlags = []cli.Flag{
 	},
 }
 
-// openHTML opens the outputted HTML file.
+// OpenHTML will attempt to open the outputted HTML file in the default browser
 func OpenHTML(r reporter.Reporter, outputPath string) {
 	// Open the outputted HTML file in the default browser.
 	r.Infof("Opening %s...\n", outputPath)

experimental/javareach/javaclass.go

@@ -10,7 +10,7 @@ import (
 )
 
 var (
-	// From https://docs.oracle.com/javase/specs/jvms/se7/html/jvms-4.html#jvms-4.3
+	// BinaryBaseTypes comes from https://docs.oracle.com/javase/specs/jvms/se7/html/jvms-4.html#jvms-4.3
 	BinaryBaseTypes = []string{
 		"B",
 		"C",

internal/clients/clientimpl/baseimagematcher/baseimagematcher.go

@@ -26,7 +26,9 @@ const (
 	DigestSHA256EmptyTar = digest.Digest("sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef")
 )
 
-// OSVMatcher implements the VulnerabilityMatcher interface with a osv.dev client.
+// DepsDevBaseImageMatcher is an implementation of clientinterfaces.BaseImageMatcher
+// that uses the deps.dev API to match base images.
+//
 // It sends out requests for every package version and does not perform caching.
 type DepsDevBaseImageMatcher struct {
 	HTTPClient http.Client

internal/config/config.go

@@ -137,8 +137,8 @@ func shouldIgnoreTimestamp(ignoreUntil time.Time) bool {
 	return ignoreUntil.After(time.Now())
 }
 
-// Sets the override config by reading the config file at configPath.
-// Will return an error if loading the config file fails
+// UseOverride updates the Manager to use the config at the given path in place
+// of any other config files that would be loaded when calling Get
 func (c *Manager) UseOverride(r reporter.Reporter, configPath string) error {
 	config, configErr := tryLoadConfig(r, configPath)
 	if configErr != nil {
@@ -149,7 +149,7 @@ func (c *Manager) UseOverride(r reporter.Reporter, configPath string) error {
 	return nil
 }
 
-// Attempts to get the config
+// Get returns the appropriate config to use based on the targetPath
 func (c *Manager) Get(r reporter.Reporter, targetPath string) Config {
 	if c.OverrideConfig != nil {
 		return *c.OverrideConfig

internal/customgitignore/walk_up_to_root.go

@@ -12,7 +12,7 @@ import (
 	"github.com/go-git/go-git/v5/plumbing/format/gitignore"
 )
 
-// Takes a dir and processes .gitignore files from it.
+// ParseGitIgnores takes a dir and processes .gitignore files from it.
 //
 // This uses go-git under the hood and returns a slice
 // of go-git's gitignore.Pattern structs.

internal/datasource/npmrc.go

@@ -128,7 +128,7 @@ func builtinNpmrc() string {
 	return npmrc
 }
 
-// Implementation of npm registry auth matching, adapted from npm-registry-fetch
+// NpmRegistryAuths handles npm registry authentication in a manner similar to npm-registry-fetch
 // https://github.com/npm/npm-registry-fetch/blob/237d33b45396caa00add61e0549cf09fbf9deb4f/lib/auth.js
 type NpmRegistryAuths map[string]*HTTPAuthentication
 

internal/osvdev/osvdev.go

@@ -36,7 +36,7 @@ type OSVClient struct {
 	BaseHostURL string
 }
 
-// DefaultClient() creates a new OSVClient with default settings
+// DefaultClient creates a new OSVClient with default settings
 func DefaultClient() *OSVClient {
 	return &OSVClient{
 		HTTPClient:  http.DefaultClient,
@@ -189,7 +189,6 @@ func (c *OSVClient) Query(ctx context.Context, query *Query) (*Response, error)
 	return &osvResp, nil
 }
 
-// ExperimentalDetermineVersion
 func (c *OSVClient) ExperimentalDetermineVersion(ctx context.Context, query *DetermineVersionsRequest) (*DetermineVersionResponse, error) {
 	requestBytes, err := json.Marshal(query)
 	if err != nil {

internal/output/html.go

@@ -10,7 +10,7 @@ import (
 	"github.com/google/osv-scanner/v2/pkg/models"
 )
 
-// HTML templates directory
+// TemplateDir is the directory containing the HTML templates
 const TemplateDir = "html/*"
 
 //go:embed html/*

internal/output/markdowntable.go

@@ -8,7 +8,7 @@ import (
 	"github.com/jedib0t/go-pretty/v6/text"
 )
 
-// PrintTableResults prints the osv scan results into a human friendly table.
+// PrintMarkdownTableResults prints the osv scan results into a human friendly table.
 func PrintMarkdownTableResults(vulnResult *models.VulnerabilityResults, outputWriter io.Writer) {
 	text.DisableColors()
 

internal/output/output_result.go

@@ -93,7 +93,7 @@ type LayerInfo struct {
 	Count         VulnCount
 }
 
-// VulnSummary represents the count of each vulnerability type at the top level
+// VulnTypeSummary represents the count of each vulnerability type at the top level
 // of the scanning results.
 type VulnTypeSummary struct {
 	All     int

internal/resolution/manifest/npm.go

@@ -306,9 +306,11 @@ func (NpmReadWriter) Write(r lockfile.DepFile, w io.Writer, patch Patch) error {
 	return err
 }
 
-// extract the real package name & version from an alias-specified version
+// SplitNPMAlias extracts the real package name and version from an alias-specified version.
+//
 // e.g. "npm:pkg@^1.2.3" -> name: "pkg", version: "^1.2.3"
-// name is empty and version is unchanged if not an alias specifier
+//
+// If the version is not an alias specifier, the name will be empty and the version unchanged.
 func SplitNPMAlias(v string) (name, version string) {
 	if r, ok := strings.CutPrefix(v, "npm:"); ok {
 		if i := strings.LastIndex(r, "@"); i > 0 {

internal/scalibrextract/ecosystemmock/extractor.go

@@ -1,4 +1,4 @@
-// ecosystemmock extractor just returns the passed in Ecosystem string from Ecosystem()
+// Package ecosystemmock provides an extractor that just returns the passed in Ecosystem string from Ecosystem()
 // This is useful when manually creating an inventory so that inv.Ecosystem() returns the ecosystem you want
 package ecosystemmock
 

internal/testutility/utility.go

@@ -34,14 +34,13 @@ func Skip(t *testing.T, args ...any) {
 	snaps.Skip(t, args...)
 }
 
-// Access to environment variable that toggles acceptance testing execution paths
-// Acceptance testing is "On" only when var set to "true"
+// IsAcceptanceTest returns true if the test suite is being run with acceptance tests enabled
 func IsAcceptanceTest() bool {
 	return os.Getenv("TEST_ACCEPTANCE") == "true"
 }
 
-// AcceptanceTests marks this test function as a extended that require additional dependencies
-// automatically skipped unless running in a CI environment
+// SkipIfNotAcceptanceTesting marks the test as skipped unless the test suite is
+// being run with acceptance tests enabled, as indicated by IsAcceptanceTest
 func SkipIfNotAcceptanceTesting(t *testing.T, reason string) {
 	t.Helper()
 	if !IsAcceptanceTest() {

internal/tui/dependency-graph.go

@@ -42,8 +42,7 @@ func subgraphEdges(sg *resolution.DependencySubgraph, direct resolve.NodeID) []r
 	return edges
 }
 
-// for each unique vulnerable node, construct the graph from that node to each connected direct dependency,
-// choosing only the shortest path
+// FindChainGraphs constructs a graph of the shortest paths from each direct dependency to each unique vulnerable node
 func FindChainGraphs(subgraphs []*resolution.DependencySubgraph) []ChainGraph {
 	// Construct the ChainGraphs
 	ret := make([]ChainGraph, 0, len(subgraphs))

internal/tui/tui.go

@@ -11,7 +11,6 @@ import (
 	"github.com/charmbracelet/lipgloss"
 )
 
-// Key bindings
 type KeyMap struct {
 	Up         key.Binding
 	Down       key.Binding
@@ -68,7 +67,7 @@ var Keys = KeyMap{
 	),
 }
 
-// Helper to have all spinners styled consistently
+// NewSpinner creates a stylised spinner
 func NewSpinner() spinner.Model {
 	sp := spinner.New(spinner.WithSpinner(spinner.Line))
 	// Spinner.FPS is actually the duration of each frame, not the frames per second
@@ -77,7 +76,7 @@ func NewSpinner() spinner.Model {
 	return sp
 }
 
-// Inline selector renderer, for layouts that don't fit neatly into a list/table
+// RenderSelectorOption provides an inline selector renderer, for layouts that don't fit neatly into a list/table
 func RenderSelectorOption(
 	selected bool, // whether this line is currently highlighted
 	cursor string, // the cursor to display before the line, if it's selected
@@ -96,15 +95,15 @@ func RenderSelectorOption(
 	return fmt.Sprintf(cursor+format, args...)
 }
 
-// tea-like model for representing the secondary info panel
-// Allows for resizing
+// ViewModel provides a tea-like model for representing the secondary info panel
+// which allows for resizing
 type ViewModel interface {
 	Update(msg tea.Msg) (ViewModel, tea.Cmd)
 	View() string
 	Resize(w, h int)
 }
 
-// Msg and Cmd to use to quit out of the ViewModel
+// ViewModelCloseMsg provides a message to close the ViewModel
 type ViewModelCloseMsg struct{}
 
 var CloseViewModel tea.Cmd = func() tea.Msg { return ViewModelCloseMsg{} }

internal/utility/maven/maven.go

@@ -21,7 +21,7 @@ const (
 // MaxParent sets a limit on the number of parents to avoid indefinite loop.
 const MaxParent = 100
 
-// MergeMavenParents parses local accessible parent pom.xml or fetches it from
+// MergeParents parses local accessible parent pom.xml or fetches it from
 // upstream, merges into root project, then interpolate the properties.
 // result holds the merged Maven project.
 // current holds the current parent project to merge.
@@ -115,9 +115,10 @@ func ProjectKey(proj maven.Project) maven.ProjectKey {
 	return proj.ProjectKey
 }
 
-// Maven looks for the parent POM first in 'relativePath',
-// then the local repository '../pom.xml',
-// and lastly in the remote repo.
+// ParentPOMPath resolves the path to the parent POM in the same manner as Maven.
+//
+// That is, it first looks for the parent POM in the 'relativePath' directory,
+// then in the parent directory, and finally in the remote repository.
 func ParentPOMPath(currentPath, relativePath string) string {
 	if relativePath == "" {
 		relativePath = "../pom.xml"

internal/utility/results/results.go

@@ -6,7 +6,7 @@ import (
 	"github.com/google/osv-scanner/v2/pkg/models"
 )
 
-// Number of characters to display a git commit
+// ShortCommitLen is the number of characters to display a git commit
 const ShortCommitLen = 8
 
 func PkgToString(pkgInfo models.PackageInfo) string {

pkg/models/results.go

@@ -7,7 +7,7 @@ import (
 	"github.com/google/osv-scalibr/extractor"
 )
 
-// Combined vulnerabilities found for the scanned packages
+// VulnerabilityResults is the top-level struct for the results of a scan
 type VulnerabilityResults struct {
 	Results                    []PackageSource            `json:"results"`
 	ExperimentalAnalysisConfig ExperimentalAnalysisConfig `json:"experimental_config"`
@@ -60,7 +60,7 @@ func getGroupInfoForVuln(groups []GroupInfo, vulnID string) GroupInfo {
 	return groups[groupIdx]
 }
 
-// Flattened Vulnerability Information.
+// VulnerabilityFlattened is a flattened version of the VulnerabilityResults
 // TODO: rename this to IssueFlattened or similar in the next major release as
 // it now contains license violations.
 type VulnerabilityFlattened struct {
@@ -87,7 +87,7 @@ func (s SourceInfo) String() string {
 	return s.Type + ":" + s.Path
 }
 
-// Vulnerabilities grouped by sources
+// PackageSource represents Vulnerabilities associated with a Source
 type PackageSource struct {
 	Source SourceInfo `json:"source"`
 	// Place Annotations in PackageSource instead of SourceInfo as we need SourceInfo to be mappable
@@ -98,7 +98,7 @@ type PackageSource struct {
 // License is an SPDX license.
 type License string
 
-// Vulnerabilities grouped by package
+// PackageVulns grouped by package
 // TODO: rename this to be Package as it now includes license information too.
 type PackageVulns struct {
 	Package           PackageInfo     `json:"package"`
@@ -191,7 +191,6 @@ type AnalysisInfo struct {
 	Unimportant bool `json:"unimportant"`
 }
 
-// Specific package information
 type PackageInfo struct {
 	Name          string              `json:"name"`
 	OSPackageName string              `json:"os_package_name,omitempty"`

pkg/osvscanner/osvscanner.go

@@ -173,7 +173,7 @@ func initializeExternalAccessors(r reporter.Reporter, actions ScannerActions) (E
 	return externalAccessors, nil
 }
 
-// Perform osv scanner action, with optional reporter to output information
+// DoScan performs the osv scanner action, with optional reporter to output information
 func DoScan(actions ScannerActions, r reporter.Reporter) (models.VulnerabilityResults, error) {
 	if r == nil {
 		r = &reporter.VoidReporter{}