stand: Add driver interface docs

[imp]

Summary

Add some rather bare-bones driver interface docs.

Sponsored by: Netflix

[rpokala]

stand/libsa/libsa.3

717

"The name of the device."

719

Is this really an int, or is it actually an enum? Perhaps an enum value stored in an int?

In any case, if there are limited valid values like an enum, then they should be listed somewhere.

723

"Drivers are"

[pauamma_gundo.com]

stand/libsa/libsa.3

719

Clarify "Gross". Rough? General?

761

While here, why isn't this just .Nm?

[imp]

stand/libsa/libsa.3

719

Is this really an int, or is it actually an enum? Perhaps an enum value stored in an int?

int with #define values. This code is a bit old-school having been around 25 years :)

[imp]

Roll all the review feedback into this update (hopefully)
Bump date based on the target commit date.

[imp]

Also document devformat

[rpokala]

stand/libsa/libsa.3

719

Is this really an int, or is it actually an enum? Perhaps an enum value stored in an int?

int with #define values. This code is a bit old-school having been around 25 years :)

Missed this response earlier. That's close enough to "enum" for our purposes here. :-)

The list of valid values should be referenced in some way, either by being listed in this document, or with a pointer to the file which contains the #defines.

722

This is C, so clarify what you mean by "subclass".

(In this case, from grepping through the code, it seems like you mean that there are multiple 'struct foo_devdesc', each of which have 'struct devdesc' as the first field'.)

[rpokala]

Based on my previous comments, I suggest something like this for dv_type:

.It dv_type
Type of device.
The supported types are:
.Bl -tag -width "DEVT_NONE"
.It DEVT_NONE
.It DEVT_DISK
.It DEVT_NET
.It DEVT_CD
.It DEVT_ZFS
.It DEVT_FD
.El
Each type may have its own associated (struct type_devdesc),
which has the generic (struct devdesc) as its first member.

(The markup might need a little tweaking, particularly the references to the structures, but that should be in the right ballpark.)

[pauamma_gundo.com]

Minor enough to fix when committing.

stand/libsa/libsa.3

509

Or "device passed in"

718

Parallel with "file name", "path name", "street name", etc.

743

(or "devdesc passed in")

[imp]

I'm going to commit what I have...
I think I got all the suggestions, but please reply if I have missed some or more occur to you...

[pauamma_gundo.com]

In D35912#829187, @imp wrote:

I'm going to commit what I have...
I think I got all the suggestions, but please reply if I have missed some or more occur to you...

https://reviews.freebsd.org/D35912#inline-221612 missing. If not deliberate, race you to fixing it.