RE: Omitting documentation for internal structure members

[Matthew Wilcox]

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

[Jani Nikula]

On Thu, 26 Jan 2017, Matthew Wilcox  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 majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Omitting documentation for internal structure members

[Matthew Wilcox]

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�