Hi,
I wouldn't normally nitpick like this but since I was reading it anyway
and you were asking for "OCD doc style thing". :-)
This is a proofread of the force-pushed v2 in drm-intel-nightly
(9a8730ddfe1d).
> + <sect1>
> + <title>Style Guidelines</title>
> + <para>
> + For consistency this documentation use American English. Abbreviations
^
s/use/uses/
> + are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so
> + on. To aid in reading documentations make full use of the markup
^
insert comma
> + characters kerneldoc provides: @parameter for function parameters, @member
> + for structure members, &structure to reference structures and
> + function() for functions. These all get automatically hyperlinked if
> + kerneldoc for the referenced objects exists. When referencing entries in
> + function vtables please use -<vfunc(). Note that kerneldoc does
^
>
> + not support referencing struct members directly, so please add a reference
> + to the vtable struct somewhere in the same paragraph or at least section.
> + </para>
> + <para>
> + Except in special situations (to separate locked from unlocked variants)
> + locking requirements for functions aren't documented in the kerneldoc.
> + Instead locking should be check at runtime using e.g.
> + <code>WARN_ON(!mutex_is_locked(...));</code>. Since it's much easier to
> + ignore documentation than runtime noise this provides more value. And on
> + top of that runtime checks do need to be updated when the locking rules
> + change, increasing the chances that they're correct. Within the
> + documentation the locking rules should be explained in the relevant
> + structures: Either in the comment for the lock explaining what it
> + protects, or data fields need a note about which lock protects them, or
> + both.
> + </para>
> + <para>
> + Functions which have a non-<code>void</code> return value should have a
> + section called "Returns" explaining the expected return values in
> + different cases and their meanings. Currently there's no consensus whether
> + that section name should be all upper-case or not, and whether it should
> + end in a colon or not. Go with the file-local style. Other common section
> + names are "Notes" with information for dangerous or tricky corner cases,
> + and "FIXME" where the interface could be cleaned up.
> + </para>
> + </sect1>
Otherwise looks nice, thank you!
Best regards,
Lukas
_______________________________________________
Intel-gfx mailing list
Intel-gfx@xxxxxxxxxxxxxxxxxxxxx
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
