update inline comments to Go v1.19 doc format

Go version 1.19 adds more support for documentation comments and
now also reformats such comments automatically, so we update a
few of them to meet the new standards.  See also:

  https://tip.golang.org/doc/go1.19#go-doc
  https://tip.golang.org/doc/comment

commands/command_lock.go

@@ -79,10 +79,10 @@ func lockCommand(cmd *cobra.Command, args []string) {
 // will be returned.
 //
 // For example:
-//     - Working directory: /code/foo/bar/
-//     - Repository root: /code/foo/
-//     - File to lock: ./baz
-//     - Resolved path bar/baz
+//   - Working directory: /code/foo/bar/
+//   - Repository root: /code/foo/
+//   - File to lock: ./baz
+//   - Resolved path bar/baz
 func lockPath(file string) (string, error) {
 	repo, err := git.RootDir()
 	if err != nil {

commands/command_post_checkout.go

@@ -13,10 +13,10 @@ import (
 // postCheckoutCommand is run through Git's post-checkout hook. The hook passes
 // up to 3 arguments on the command line:
 //
-//   1. SHA of previous commit before the checkout
-//   2. SHA of commit just checked out
-//   3. Flag ("0" or "1") - 1 if a branch/tag/SHA was checked out, 0 if a file was
-//      In the case of a file being checked out, the pre/post SHA are the same
+//  1. SHA of previous commit before the checkout
+//  2. SHA of commit just checked out
+//  3. Flag ("0" or "1") - 1 if a branch/tag/SHA was checked out, 0 if a file was
+//     In the case of a file being checked out, the pre/post SHA are the same
 //
 // This hook checks that files which are lockable and not locked are made read-only,
 // optimising that as best it can based on the available information.

commands/command_pre_push.go

@@ -19,16 +19,17 @@ var (
 // prePushCommand is run through Git's pre-push hook. The pre-push hook passes
 // two arguments on the command line:
 //
-//   1. Name of the remote to which the push is being done
-//   2. URL to which the push is being done
+//  1. Name of the remote to which the push is being done
+//  2. URL to which the push is being done
 //
 // The hook receives commit information on stdin in the form:
-//   <local ref> <local sha1> <remote ref> <remote sha1>
+//
+//	<local ref> <local sha1> <remote ref> <remote sha1>
 //
 // In the typical case, prePushCommand will get a list of git objects being
 // pushed by using the following:
 //
-//    git rev-list --objects <local sha1> ^<remote sha1>
+//	git rev-list --objects <local sha1> ^<remote sha1>
 //
 // If any of those git objects are associated with Git LFS objects, those
 // objects will be pushed to the Git LFS API.
@@ -65,7 +66,7 @@ func prePushCommand(cmd *cobra.Command, args []string) {
 
 // prePushRefs parses commit information that the pre-push git hook receives:
 //
-//   <local ref> <local sha1> <remote ref> <remote sha1>
+//	<local ref> <local sha1> <remote ref> <remote sha1>
 //
 // Each line describes a proposed update of the remote ref at the remote sha to
 // the local sha. Multiple updates can be received on multiple lines (such as

commands/command_push.go

@@ -24,10 +24,10 @@ var (
 
 // pushCommand pushes local objects to a Git LFS server.  It has four forms:
 //
-//   `<remote> <ref>...`
-//   `<remote> --stdin`              (reads refs from stdin)
-//   `<remote> --object-id <oid>...`
-//   `<remote> --object-id --stdin`  (reads oids from stdin)
+//	`<remote> <ref>...`
+//	`<remote> --stdin`              (reads refs from stdin)
+//	`<remote> --object-id <oid>...`
+//	`<remote> --object-id --stdin`  (reads oids from stdin)
 //
 // Remote must be a remote name, not a URL. With --stdin, values are newline
 // separated.

commands/command_status.go

@@ -336,7 +336,7 @@ func porcelainStatusLine(entry *lfs.DiffIndexEntry) string {
 // relativize relatives a path from "from" to "to". For instance, note that, for
 // any paths "from" and "to", that:
 //
-//   to == filepath.Clean(filepath.Join(from, relativize(from, to)))
+//	to == filepath.Clean(filepath.Join(from, relativize(from, to)))
 func relativize(from, to string) string {
 	if len(from) == 0 {
 		return to

commands/path_windows.go

@@ -27,16 +27,16 @@ func osLineEnding() string {
 // the actual Windows directory, but with forward slashes. You can see this
 // for yourself:
 //
-//   $ git /foo
-//   git: 'C:/Program Files/Git/foo' is not a git command. See 'git --help'.
+//	$ git /foo
+//	git: 'C:/Program Files/Git/foo' is not a git command. See 'git --help'.
 //
 // You can check the path with `pwd -W`:
 //
-//   $ cd /
-//   $ pwd
-//   /
-//   $ pwd -W
-//   c:/Program Files/Git
+//	$ cd /
+//	$ pwd
+//	/
+//	$ pwd -W
+//	c:/Program Files/Git
 func cleanRootPath(pattern string) string {
 	winBashMu.Lock()
 	defer winBashMu.Unlock()

config/config.go

@@ -522,9 +522,9 @@ func (c *Configuration) UnsetGitLocalKey(key string) (string, error) {
 
 // loadGitConfig is a temporary measure to support legacy behavior dependent on
 // accessing properties set by ReadGitConfig, namely:
-//  - `c.extensions`
-//  - `c.uniqRemotes`
-//  - `c.gitConfig`
+//   - `c.extensions`
+//   - `c.uniqRemotes`
+//   - `c.gitConfig`
 //
 // Since the *gitEnvironment is responsible for setting these values on the
 // (*config.Configuration) instance, we must call that method, if it exists.

config/environment.go

@@ -107,10 +107,10 @@ func Int(value string, def int) int {
 // The "boolean state associated with a given key" is defined as the
 // case-insensitive string comparison with the following:
 //
-// 1) true if...
-//   "true", "1", "on", "yes", or "t"
-// 2) false if...
-//   "false", "0", "off", "no", "f", or otherwise.
+//  1. true if...
+//     "true", "1", "on", "yes", or "t"
+//  2. false if...
+//     "false", "0", "off", "no", "f", or otherwise.
 func Bool(value string, def bool) bool {
 	if len(value) == 0 {
 		return def

git/filter_process_scanner.go

@@ -18,15 +18,15 @@ import (
 //
 // Reading a request (and errors) is as follows:
 //
-//     s := NewFilterProcessScanner(os.Stdin, os.Stderr)
-//     for s.Scan() {
-//             req := s.Request()
-//     	       // ...
-//     }
+//	s := NewFilterProcessScanner(os.Stdin, os.Stderr)
+//	for s.Scan() {
+//	        req := s.Request()
+//		       // ...
+//	}
 //
-//     if err := s.Err(); err != nil {
-//             // ...
-//     }
+//	if err := s.Err(); err != nil {
+//	        // ...
+//	}
 type FilterProcessScanner struct {
 	// pl is the *pktline instance used to read and write packets back and
 	// forth between Git.

git/git.go

@@ -112,7 +112,7 @@ type Ref struct {
 // for a remote branch called 'my-feature' on remote 'origin', this function
 // will return:
 //
-//   refs/remotes/origin/my-feature
+//	refs/remotes/origin/my-feature
 func (r *Ref) Refspec() string {
 	if r == nil {
 		return ""

git/githistory/rewriter.go

@@ -139,7 +139,6 @@ type TreePreCallbackFn func(path string, t *gitobj.Tree) error
 // written to the object database instead of one generated from calling BlobFn
 // on all of the tree entries.
 //
-//
 // TreeCallbackFn can be nil, and will therefore exhibit behavior equivalent to
 // only calling the BlobFn on existing tree entries.
 //

lfsapi/auth.go

@@ -124,16 +124,16 @@ func (c *Client) doWithCreds(req *http.Request, credWrapper creds.CredentialHelp
 //
 // There are three URLs in play, that make this a little confusing.
 //
-// 1. The request URL, which should be something like "https://git.com/repo.git/info/lfs/objects/batch"
-// 2. The LFS API URL, which should be something like "https://git.com/repo.git/info/lfs"
-//    This URL used for the "lfs.URL.access" git config key, which determines
-//    what kind of auth the LFS server expects. Could be BasicAccess,
-//    NTLMAccess, NegotiateAccess, or NoneAccess, in which the Git Credential
-//    Helper step is skipped. We do not want to prompt the user for a password
-//    to fetch public repository data.
-// 3. The Git Remote URL, which should be something like "https://git.com/repo.git"
-//    This URL is used for the Git Credential Helper. This way existing https
-//    Git remote credentials can be re-used for LFS.
+//  1. The request URL, which should be something like "https://git.com/repo.git/info/lfs/objects/batch"
+//  2. The LFS API URL, which should be something like "https://git.com/repo.git/info/lfs"
+//     This URL used for the "lfs.URL.access" git config key, which determines
+//     what kind of auth the LFS server expects. Could be BasicAccess,
+//     NTLMAccess, NegotiateAccess, or NoneAccess, in which the Git Credential
+//     Helper step is skipped. We do not want to prompt the user for a password
+//     to fetch public repository data.
+//  3. The Git Remote URL, which should be something like "https://git.com/repo.git"
+//     This URL is used for the Git Credential Helper. This way existing https
+//     Git remote credentials can be re-used for LFS.
 func (c *Client) getCreds(remote string, access creds.Access, req *http.Request) (creds.CredentialHelperWrapper, error) {
 	ef := c.Endpoints
 	if ef == nil {

lfshttp/endpoint.go

@@ -65,9 +65,8 @@ func EndpointFromSshUrl(u *url.URL) Endpoint {
 
 // EndpointFromBareSshUrl constructs a new endpoint from a bare SSH URL:
 //
-//   [email protected]:path/to/repo.git or
-//   [[email protected]:port]:path/to/repo.git
-//
+//	[email protected]:path/to/repo.git or
+//	[[email protected]:port]:path/to/repo.git
 func EndpointFromBareSshUrl(rawurl string) Endpoint {
 	parts := strings.Split(rawurl, ":")
 	partsLen := len(parts)

locking/locks.go

@@ -140,7 +140,7 @@ func (c *Client) LockFile(path string) (Lock, error) {
 // For instance, given a repository in /usr/local/src/my-repo and a file called
 // dir/foo/bar.txt, getAbsolutePath will return:
 //
-//   /usr/local/src/my-repo/dir/foo/bar.txt
+//	/usr/local/src/my-repo/dir/foo/bar.txt
 func getAbsolutePath(p string) (string, error) {
 	root, err := git.RootDir()
 	if err != nil {

tasklog/list_task.go

@@ -9,9 +9,10 @@ import (
 // entry is line-delimited.
 //
 // For example:
-//   entry #1
-//   entry #2
-//   msg: ..., done.
+//
+//	entry #1
+//	entry #2
+//	msg: ..., done.
 type ListTask struct {
 	msg string
 	ch  chan *Update

tools/filetools.go

@@ -244,11 +244,11 @@ type FastWalkCallback func(parentDir string, info os.FileInfo, err error)
 // repo. The callback guaranteed to be called sequentially. The function returns
 // once all files and errors have triggered callbacks.
 // It differs in the following ways:
-//  * Uses goroutines to parallelise large dirs and descent into subdirs
-//  * Does not provide sorted output; parents will always be before children but
-//    there are no other guarantees. Use parentDir argument in the callback to
-//    determine absolute path rather than tracking it yourself
-//  * Automatically ignores any .git directories
+//   - Uses goroutines to parallelise large dirs and descent into subdirs
+//   - Does not provide sorted output; parents will always be before children but
+//     there are no other guarantees. Use parentDir argument in the callback to
+//     determine absolute path rather than tracking it yourself
+//   - Automatically ignores any .git directories
 //
 // rootDir - Absolute path to the top of the repository working directory
 func FastWalkDir(rootDir string, cb FastWalkCallback) {

tools/str_tools.go

@@ -16,10 +16,12 @@ var (
 // pairs of quotation delimiters.
 //
 // For instance, the quoted fields of the string "foo bar 'baz etc'" would be:
-//   []string{"foo", "bar", "baz etc"}
+//
+//	[]string{"foo", "bar", "baz etc"}
 //
 // Whereas the same argument given to strings.Fields, would return:
-//   []string{"foo", "bar", "'baz", "etc'"}
+//
+//	[]string{"foo", "bar", "'baz", "etc'"}
 func QuotedFields(s string) []string {
 	submatches := quoteFieldRe.FindAllStringSubmatch(s, -1)
 	out := make([]string, 0, len(submatches))

tq/transfer_queue.go

@@ -398,22 +398,22 @@ func (q *TransferQueue) remember(t *objectTuple) objects {
 // collectBatches collects batches in a loop, prioritizing failed items from the
 // previous before adding new items. The process works as follows:
 //
-//   1. Create a new batch, of size `q.batchSize`, and containing no items
-//   2. While the batch contains less items than `q.batchSize` AND the channel
-//      is open, read one item from the `q.incoming` channel.
-//      a. If the read was a channel close, go to step 4.
-//      b. If the read was a transferable item, go to step 3.
-//   3. Append the item to the batch.
-//   4. Sort the batch by descending object size, make a batch API call, send
-//      the items to the `*adapterBase`.
-//   5. In a separate goroutine, process the worker results, incrementing and
-//      appending retries if possible. On the main goroutine, accept new items
-//      into "pending".
-//   6. Concat() the "next" and "pending" batches such that no more items than
-//      the maximum allowed per batch are in next, and the rest are in pending.
-//   7. If the `q.incoming` channel is open, go to step 2.
-//   8. If the next batch is empty AND the `q.incoming` channel is closed,
-//      terminate immediately.
+//  1. Create a new batch, of size `q.batchSize`, and containing no items
+//  2. While the batch contains less items than `q.batchSize` AND the channel
+//     is open, read one item from the `q.incoming` channel.
+//     a. If the read was a channel close, go to step 4.
+//     b. If the read was a transferable item, go to step 3.
+//  3. Append the item to the batch.
+//  4. Sort the batch by descending object size, make a batch API call, send
+//     the items to the `*adapterBase`.
+//  5. In a separate goroutine, process the worker results, incrementing and
+//     appending retries if possible. On the main goroutine, accept new items
+//     into "pending".
+//  6. Concat() the "next" and "pending" batches such that no more items than
+//     the maximum allowed per batch are in next, and the rest are in pending.
+//  7. If the `q.incoming` channel is open, go to step 2.
+//  8. If the next batch is empty AND the `q.incoming` channel is closed,
+//     terminate immediately.
 //
 // collectBatches runs in its own goroutine.
 func (q *TransferQueue) collectBatches() {