Re: [patch 1/4] DocBook: allow to mark structure members private

["Randy.Dunlap" <rdunlap@xenotime.net>]

On Mon, 07 Nov 2005 23:54:10 +0100 Martin Waitz wrote:

> DocBook: allow to mark structure members private
> 
> Many structures contain both an internal part and one which is part of the
> API to other modules.  With this patch it is possible to only include
> these public members in the kernel documentation.
> 
> Signed-off-by: Martin Waitz <tali@admingilde.org>


Ahoy.  Excellent.  Compare my personal todo list item:

35.for kernel-doc: make some fields :private: so that a description is not
    expected for them.


Just to be clear about the usage, the kernel-doc script switches from
public to private upon seeing a /*-style comment with the strings
"private:" or "public:" in it.  Right?

Yes, a lot of those USB header fields did need some help.
That's why my todo item was there.


> ---
>  include/linux/usb.h |    6 +++---
>  scripts/kernel-doc  |   13 +++++++++++--
>  2 files changed, 14 insertions(+), 5 deletions(-)
> 
> Index: linux-docbook/scripts/kernel-doc
> ===================================================================
> --- linux-docbook.orig/scripts/kernel-doc	2005-11-04 22:55:27.236188385 +0100
> +++ linux-docbook/scripts/kernel-doc	2005-11-04 23:13:29.348626536 +0100
> @@ -1304,6 +1306,12 @@ sub dump_struct($$) {
>  	# ignore embedded structs or unions
>  	$members =~ s/{.*?}//g;
>  
> +	# ignore members marked private:
> +	$members =~ s/\/\*.*?private:.*?public:.*?\*\///gos;
> +	$members =~ s/\/\*.*?private:.*//gos;
> +	# strip comments:
> +	$members =~ s/\/\*.*?\*\///gos;
> +
>  	create_parameterlist($members, ';', $file);
>  
>  	output_declaration($declaration_name,
> Index: linux-docbook/include/linux/usb.h
> ===================================================================
> --- linux-docbook.orig/include/linux/usb.h	2005-11-04 22:57:57.356783495 +0100
> +++ linux-docbook/include/linux/usb.h	2005-11-04 23:14:05.326614355 +0100
> @@ -819,7 +819,7 @@ typedef void (*usb_complete_t)(struct ur
>   */
>  struct urb
>  {
> -	/* private, usb core and host controller only fields in the urb */
> +	/* private: usb core and host controller only fields in the urb */
>  	struct kref kref;		/* reference count of the URB */
>  	spinlock_t lock;		/* lock for the URB */
>  	void *hcpriv;			/* private data for host controller */
> @@ -827,7 +827,7 @@ struct urb
>  	atomic_t use_count;		/* concurrent submissions counter */
>  	u8 reject;			/* submissions will fail */
>  
> -	/* public, documented fields in the urb that can be used by drivers */
> +	/* public: documented fields in the urb that can be used by drivers */
>  	struct list_head urb_list;	/* list head for use by the urb's
>  					 * current owner */
>  	struct usb_device *dev; 	/* (in) pointer to associated device */
> @@ -1045,7 +1045,7 @@ struct usb_sg_request {
>  	size_t			bytes;
>  
>  	/* 
> -	 * members below are private to usbcore,
> +	 * members below are private: to usbcore,
>  	 * and are not provided for driver access!
>  	 */
>  	spinlock_t		lock;
> 
> --


---
~Randy