On Thu, 12 Feb 2015, Randy Dunlap wrote:
> On 02/12/15 03:02, Robert P. J. Day wrote:
... snip ...
> > 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.
as you can see, you *can* document private members, but if that
should be supported, then just remove the warnings that generates. or
something.
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
