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.
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?
rday
--
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================
--
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
