Omitting documentation for internal structure members

[Matthew Wilcox <mawilcox@xxxxxxxxxxxxx>]

Here's a little glitch that I'd like to see fixed:

struct radix_tree_iter
radix tree iterator state
Definition
struct radix_tree_iter {
  unsigned long index;
  unsigned long next_index;
  unsigned long tags;
  struct radix_tree_node * node;
#ifdef CONFIG_RADIX_TREE_MULTIORDER
  unsigned int shift;
#endif
};

I'd like to see the ifdef/endif not included, and the 'unsigned int shift' not included either.

I think it's appropriate to not include any preprocessor lines in the definition of the struct (general agreement on that front?)

Then I'd like a way to indicate to kernel-doc that I want to omit 'shift' from the struct definition.  It's not for public use; there's an accessor to get at it, and I don't want it documented.  If there isn't already a way to indicate this to kernel-doc, might I suggest this little gem ...

/**
 * struct radix_tree_iter - radix tree iterator state
 * @index:      index of current slot
 * @next_index: one beyond the last index for this chunk
 * @tags:       bit-mask for tag-iterating
 * @node:       node that contains current slot
 - @shift:      shift for the node that holds our slots
 *
 * The radix tree iterator works in terms of "chunks" of slots.  A chunk is a
 * subinterval of slots contained within one radix tree leaf node.  It is
 * described by a pointer to its first slot and a struct radix_tree_iter
 * which holds the chunk's position in the tree and its size.  For tagged
 * iteration radix_tree_iter also holds the slots' bit-mask for one chosen
 * radix tree tag.
 */

If the line starts with a '-' instead of a '*', that indicates that this definition should be omitted.  We're still documenting it for internal usage, but it doesn't appear in the public documentation.  Does that seem reasonable, or am I just being weird?

��.n��������+%������w��{.n�����{����*jg��������ݢj����G�������j:+v���w�m������w�������h�����٥