Skip to content

Commit

Permalink
[PATCH] DocBook: allow to mark structure members private
Browse files Browse the repository at this point in the history
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>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
  • Loading branch information
Martin Waitz authored and Linus Torvalds committed Nov 14, 2005
1 parent f5f4917 commit aeec46b
Show file tree
Hide file tree
Showing 2 changed files with 14 additions and 5 deletions.
6 changes: 3 additions & 3 deletions include/linux/usb.h
Original file line number Diff line number Diff line change
Expand Up @@ -819,15 +819,15 @@ typedef void (*usb_complete_t)(struct urb *, struct pt_regs *);
*/
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 */
int bandwidth; /* bandwidth for INT/ISO request */
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 */
Expand Down Expand Up @@ -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;
Expand Down
13 changes: 11 additions & 2 deletions scripts/kernel-doc
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,8 @@ use strict;
# struct my_struct {
# int a;
# int b;
# /* private: */
# int c;
# };
#
# All descriptions can be multiline, except the short function description.
Expand Down Expand Up @@ -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,
Expand All @@ -1329,6 +1337,7 @@ sub dump_enum($$) {
my $x = shift;
my $file = shift;

$x =~ s@/\*.*?\*/@@gos; # strip comments.
if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
$declaration_name = $1;
my $members = $2;
Expand Down Expand Up @@ -1365,6 +1374,7 @@ sub dump_typedef($$) {
my $x = shift;
my $file = shift;

$x =~ s@/\*.*?\*/@@gos; # strip comments.
while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
$x =~ s/\(*.\)\s*;$/;/;
$x =~ s/\[*.\]\s*;$/;/;
Expand Down Expand Up @@ -1420,7 +1430,7 @@ sub create_parameterlist($$$) {
$type = $arg;
$type =~ s/([^\(]+\(\*)$param/$1/;
push_parameter($param, $type, $file);
} else {
} elsif ($arg) {
$arg =~ s/\s*:\s*/:/g;
$arg =~ s/\s*\[/\[/g;

Expand Down Expand Up @@ -1628,7 +1638,6 @@ sub process_state3_type($$) {
my $x = shift;
my $file = shift;

$x =~ s@/\*.*?\*/@@gos; # strip comments.
$x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
$x =~ s@^\s+@@gos; # strip leading spaces
$x =~ s@\s+$@@gos; # strip trailing spaces
Expand Down

0 comments on commit aeec46b

Please sign in to comment.