On 02/12/15 03:02, Robert P. J. Day wrote:
>
> more nitpickery ... howto talks about marking some structure members
> as "private:" so they don't show up in the final output. however, some
> people seem to have a confused idea of whether they still need to
> write kernel-doc content for private members.
>
> here's a snippet from include/linux/hsi/hsi.h (whose content shows
> up in the device-drivers manual):
>
> /**
> * struct hsi_client - HSI client attached to an HSI port
> * @device: Driver model representation of the device
> * @tx_cfg: HSI TX configuration
> * @rx_cfg: HSI RX configuration
> * e_handler: Callback for handling port events (RX Wake High/Low)
> * pclaimed: Keeps tracks if the clients claimed its associated HSI port
> * nb: Notifier block for port events
> */
> struct hsi_client {
> struct device device;
> struct hsi_config tx_cfg;
> struct hsi_config rx_cfg;
> /* private: */
> void (*ehandler)(struct hsi_client *, unsigned long);
> unsigned int pclaimed:1;
> struct notifier_block nb;
> };
>
> note how the author seemed to think leaving off the leading "@" in
> the kernel-doc was the thing to do for private members -- all that
> does is generate a page where those last three member names are
> treated as section headers, see for yourself at the generated HTML
> page device-drivers/API-struct-hsi-client.html. so this is pretty
> clearly not what one should do.
You are correct.
> OTOH, here's a snippet from include/linux/bch.h (not included in any
> manual):
>
> /**
> * struct bch_control - BCH control structure
> * @m: Galois field order
> * @n: maximum codeword size in bits (= 2^m-1)
> * @t: error correction capability in bits
> * @ecc_bits: ecc exact size in bits, i.e. generator polynomial degree (<=m*t)
> * @ecc_bytes: ecc max size (m*t bits) in bytes
> * @a_pow_tab: Galois field GF(2^m) exponentiation lookup table
> * @a_log_tab: Galois field GF(2^m) log lookup table
> * @mod8_tab: remainder generator polynomial lookup tables
> * @ecc_buf: ecc parity words buffer
> * @ecc_buf2: ecc parity words buffer
> * @xi_tab: GF(2^m) base for solving degree 2 polynomial roots
> * @syn: syndrome buffer
> * @cache: log-based polynomial representation buffer
> * @elp: error locator polynomial
> * @poly_2t: temporary polynomials of degree 2t
> */
> struct bch_control {
> unsigned int m;
> unsigned int n;
> unsigned int t;
> unsigned int ecc_bits;
> unsigned int ecc_bytes;
> /* private: */
> uint16_t *a_pow_tab;
> uint16_t *a_log_tab;
> uint32_t *mod8_tab;
> ... snip ...
>
> where the author has properly "documented" private members. what this
> would do is generate a warning for each private member during the
> build:
>
> Excess struct/union/enum/typedef member ...
>
> but would (i believe) generate the correct output -- only the public
> structure members would end up in the manual.
>
> so what should people be told to do? first, they can simply not
> document private members -- no problem.
>
> but if they choose to (for their own reasons), then either they
> will:
>
> 1) do it incorrectly and get junk in their manual, or
> 2) get correct output, but numerous build warnings.
>
> thoughts?
I had always expected private struct members to have no kernel-doc
lines at all, but I think that it would be nice for us to allow those
fields to be documented but not printed.
--
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
