On Thu, 26 Jan 2017, Matthew Wilcox <mawilcox@xxxxxxxxxxxxx> wrote:
> 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 ...
You can use /* private: */ within the struct to indicate the following
members should not be included in the generated documentation. It does
however mean you can't then document the members either, or you'll get
warnings.
I'm generally not too happy about the mechanism, but it's there, perhaps
not very well advertized.
>
> /**
> * 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?
The request isn't weird, but I find the '-' prefixes there aesthetically
displeasing. I think I'd prefer fixing this in the inline member
documentation comments using some keyword/syntax. But then you'd have to
document the private fields within the struct comments.
BR,
Jani.
--
Jani Nikula, Intel Open Source Technology Center
--
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
