RE: Omitting documentation for internal structure members
From: Jani Nikula [mailto:jani.nik...@linux.intel.com] > 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. I don't know how I failed to see that in the documentation. I read doc-guide/kernel-doc.rst about three times this week. @@ -154,6 +157,7 @@ struct radix_tree_iter { unsigned long next_index; unsigned long tags; struct radix_tree_node *node; +/* private: Do not use directly; call iter_shift() or __set_iter_shift() */ #ifdef CONFIG_RADIX_TREE_MULTIORDER unsigned intshift; #endif That solves my problem. Thanks!
Re: Omitting documentation for internal structure members
On Thu, 26 Jan 2017, Matthew Wilcoxwrote: > 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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Omitting documentation for internal structure members
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�r��yb�X��ǧv�^�){.n�+{�v�"��^n�r���z���h�&���G���h�(�階�ݢj"���m��z�ޖ���f���h���~�m�