mountinfo: docs nits

[kolyshkin]

mountinfo: docs nits

1. Add a "custom file" use case to GetMountsFromReader.

2. Remove obsoleted old comment from parseMountTable.

mountinfo.Info: refresh doc

Refresh documentation about mountinfo.Info fields, based on the latest
proc(5) from man-pages v5.08.

[thaJeztah]

Curious; how does the documentation show these combined comments? Does it repeat the same doc for each of them, or does it also should them grouped?

[kolyshkin]

1. go doc shows it as is:

	// Major and Minor are the major and the minor components of the Dev
	// field of unix.Stat_t structure returned by unix.*Stat calls for
	// files on this filesystem.
	Major, Minor int

2. go doc (a webserver) does exactly the same since it's a struct members:

type Info
Info reveals information about a particular mounted filesystem. This struct is populated from the content in the /proc/<pid>/mountinfo file.

type Info struct {
    // ID is a unique identifier of the mount (may be reused after umount).
    ID int

    // Parent is the ID of the parent mount (or of self for the root
    // of this mount namespace's mount tree).
    Parent int

    // Major and Minor are the major and the minor components of the Dev
    // field of unix.Stat_t structure returned by unix.*Stat calls for
    // files on this filesystem.
    Major, Minor int
...

[thaJeztah]

Ah, yes, had wires crossed and thought we were in a var() block 🤦

makes sense

[thaJeztah]

Suggested change

	// VFSOptions is per-superblock options, comma-separated.
	// VFSOptions are per-superblock options, comma-separated.

or

Suggested change

	// VFSOptions is per-superblock options, comma-separated.
	// VFSOptions represents per-superblock options, comma-separated.

[kolyshkin]

Not a native speaker, but VFSOptions is a (single) variable, so AFAICS using plural is wrong here, as we don't describe the "options", but a variable.

[kolyshkin]

Also, if it would be plural, we'd say "VFSOptions represent". See, this feels wrong -- as we don't talk about options (plural), but a variable (singular).

[thaJeztah]

we don't describe the "options", but a variable.
Also, if it would be plural, we'd say "VFSOptions represent". See, this feels wrong -- as we don't talk about options (plural), but a variable (singular).

Yes, you're right; it should be describing the variable, not the options in the variable.

Something feels "off" in using is here, and I think I just found the problem/solution; usually (in case of a "slice"); how about this:

Suggested change

	// VFSOptions is per-superblock options, comma-separated.
	// VFSOptions is a comma-separated list of per-superblock options.

Perhaps the per- could be dropped (?)

Suggested change

	// VFSOptions is per-superblock options, comma-separated.
	// VFSOptions is a comma-separated list of superblock options.

[thaJeztah]

Suggested change

	// Options is per mount options, comma-separated.
	// Options are per mount options, comma-separated.

or perhaps

Suggested change

	// Options is per mount options, comma-separated.
	// Options represents per mount options, comma-separated.

or s/represents/stores/ or s/represents/holds/ ?

[kolyshkin]

I don't like the term "represents" here (as it implies some kind of conversion).

I don't like "stores" or "holds", as this is a string, and yes, it stores some value but it's kinda obvious.

Brevity is good here.

[thaJeztah]

see my other comment, I think we can use the same approach here;

Suggested change

	// Options is per mount options, comma-separated.
	// Options is a comma-separated list of per mount options.

Could perhaps omit the per here (?);

Suggested change

	// Options is per mount options, comma-separated.
	// Options is a comma-separated list of mount options.

[thaJeztah]

Suggested change

	// that provide a fake mountinfo data, or when a source other
	// that provide fake mountinfo data, or when a source other

[kolyshkin]

yep, fixed!

[kolyshkin]

@thaJeztah addressed your comments, PTAL

[thaJeztah]

we don't describe the "options", but a variable.
Also, if it would be plural, we'd say "VFSOptions represent". See, this feels wrong -- as we don't talk about options (plural), but a variable (singular).

Yes, you're right; it should be describing the variable, not the options in the variable.

Something feels "off" in using is here, and I think I just found the problem/solution; usually (in case of a "slice"); how about this:

Suggested change

	// VFSOptions is per-superblock options, comma-separated.
	// VFSOptions is a comma-separated list of per-superblock options.

Perhaps the per- could be dropped (?)

Suggested change

	// VFSOptions is per-superblock options, comma-separated.
	// VFSOptions is a comma-separated list of superblock options.

[thaJeztah]

see my other comment, I think we can use the same approach here;

Suggested change

	// Options is per mount options, comma-separated.
	// Options is a comma-separated list of per mount options.

Could perhaps omit the per here (?);

Suggested change

	// Options is per mount options, comma-separated.
	// Options is a comma-separated list of mount options.

[kolyshkin]

The wording ("per-superblock" and "per-mount") was taken from proc(5) man page, but I have changed it according to last review from @thaJeztah. PTAL

[thaJeztah]

The wording ("per-superblock" and "per-mount") was taken from proc(5) man page

Ah! Didn't know. I guess removing it is ok (if we hear it's not clear we could always add back the per-)

[thaJeztah]

LGTM, thanks!