lkml.org 
[lkml]   [2005]   [Nov]   [7]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    Date
    From
    SubjectRe: [patch 1/4] DocBook: allow to mark structure members private
    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
    -
    To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
    the body of a message to majordomo@vger.kernel.org
    More majordomo info at http://vger.kernel.org/majordomo-info.html
    Please read the FAQ at http://www.tux.org/lkml/

    \
     
     \ /
      Last update: 2005-11-08 04:58    [W:0.027 / U:89.972 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site