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 <[email protected]>
---
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
@@ -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.
@@ -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,
@@ -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;
@@ -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*;$/;/;
@@ -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;
@@ -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
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;
--
Martin Waitz
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 <[email protected]>
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
hoi :)
On Mon, Nov 07, 2005 at 07:40:44PM -0800, Randy.Dunlap wrote:
> 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?
exactly.
For now I only changed those comments that already made it clear
what was private and public. Feel free to add more private fields! :-)
--
Martin Waitz
Randy Dunlap wrote:
> 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.
Aha! A kernel-doc hacker! Randy, by any chance, do you have "support for
nested structs" in your TODO? And if yes, what's the status? I have
parsing with the following syntax:
# /**
# * struct my_struct - short description
# * @a: first member
# * @b: second member
+# * @c: nested struct
+# * @c.p: first member of nested struct
+# * @c.q: second member of nested struct
# *
# * Longer description
# */
# struct my_struct {
# int a;
# int b;
+# struct her_struct {
+# char **p;
+# short q;
+# } c;
# };
But properly nested displaying is in pretty much nil state since .. uh
crap.. summer.
On Tue, 8 Nov 2005, Alexey Dobriyan wrote:
> Randy Dunlap wrote:
> > 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.
>
> Aha! A kernel-doc hacker! Randy, by any chance, do you have "support for
> nested structs" in your TODO? And if yes, what's the status? I have
> parsing with the following syntax:
Hi,
Nope, haven't seen that one yet.
> # /**
> # * struct my_struct - short description
> # * @a: first member
> # * @b: second member
> +# * @c: nested struct
> +# * @c.p: first member of nested struct
> +# * @c.q: second member of nested struct
> # *
> # * Longer description
> # */
> # struct my_struct {
> # int a;
> # int b;
> +# struct her_struct {
> +# char **p;
> +# short q;
> +# } c;
> # };
>
> But properly nested displaying is in pretty much nil state since .. uh
> crap.. summer.
Is this something that used to work? If so, when?
--
~Randy
On Tue, Nov 08, 2005 at 10:27:01AM -0800, Randy.Dunlap wrote:
> On Tue, 8 Nov 2005, Alexey Dobriyan wrote:
> > # /**
> > # * struct my_struct - short description
> > # * @a: first member
> > # * @b: second member
> > +# * @c: nested struct
> > +# * @c.p: first member of nested struct
> > +# * @c.q: second member of nested struct
> > # *
> > # * Longer description
> > # */
> > # struct my_struct {
> > # int a;
> > # int b;
> > +# struct her_struct {
> > +# char **p;
> > +# short q;
> > +# } c;
> > # };
> >
> > But properly nested displaying is in pretty much nil state since .. uh
> > crap.. summer.
>
> Is this something that used to work? If so, when?
IIRC, I've done it to the state where it would print:
int a;
int b;
char **c.p;
short c.q;
but that's not C.
P. S.: Is htmldocs broken for someone else?
XMLTO Documentation/DocBook/wanbook.html
XPath error : Undefined variable
compilation error: file file:///usr/share/sgml/docbook/xsl-stylesheets-1.66.1/xhtml/docbook.xsl
line 114 element copy-of
xsl:copy-of : could not compile select expression '$title'
XPath error : Undefined variable
$html.stylesheet != ''
^
...
On Tue, 8 Nov 2005, Alexey Dobriyan wrote:
> On Tue, Nov 08, 2005 at 10:27:01AM -0800, Randy.Dunlap wrote:
> > On Tue, 8 Nov 2005, Alexey Dobriyan wrote:
> > > # /**
> > > # * struct my_struct - short description
> > > # * @a: first member
> > > # * @b: second member
> > > +# * @c: nested struct
> > > +# * @c.p: first member of nested struct
> > > +# * @c.q: second member of nested struct
> > > # *
> > > # * Longer description
> > > # */
> > > # struct my_struct {
> > > # int a;
> > > # int b;
> > > +# struct her_struct {
> > > +# char **p;
> > > +# short q;
> > > +# } c;
> > > # };
> > >
> > > But properly nested displaying is in pretty much nil state since .. uh
> > > crap.. summer.
> >
> > Is this something that used to work? If so, when?
>
> IIRC, I've done it to the state where it would print:
>
> int a;
> int b;
> char **c.p;
> short c.q;
>
> but that's not C.
>
> P. S.: Is htmldocs broken for someone else?
>
> XMLTO Documentation/DocBook/wanbook.html
> XPath error : Undefined variable
> compilation error: file file:///usr/share/sgml/docbook/xsl-stylesheets-1.66.1/xhtml/docbook.xsl
> line 114 element copy-of
> xsl:copy-of : could not compile select expression '$title'
> XPath error : Undefined variable
> $html.stylesheet != ''
> ^
> ...
Is that after applying Martin's docbook patches yesterday?
(I haven't tested that yet.)
--
~Randy
On Tue, Nov 08, 2005 at 10:48:56AM -0800, Randy.Dunlap wrote:
> On Tue, 8 Nov 2005, Alexey Dobriyan wrote:
> > P. S.: Is htmldocs broken for someone else?
> >
> > XMLTO Documentation/DocBook/wanbook.html
> > XPath error : Undefined variable
> > compilation error: file file:///usr/share/sgml/docbook/xsl-stylesheets-1.66.1/xhtml/docbook.xsl
> > line 114 element copy-of
> > xsl:copy-of : could not compile select expression '$title'
> > XPath error : Undefined variable
> > $html.stylesheet != ''
> > ^
> > ...
>
> Is that after applying Martin's docbook patches yesterday?
> (I haven't tested that yet.)
Unless they're in a very recent -linus. Probably this is a sign to test
those patches. :-)
hoi :)
On Tue, Nov 08, 2005 at 10:26:42PM +0300, Alexey Dobriyan wrote:
> > > XMLTO Documentation/DocBook/wanbook.html
> > > XPath error : Undefined variable
> > > compilation error: file file:///usr/share/sgml/docbook/xsl-stylesheets-1.66.1/xhtml/docbook.xsl
> > > line 114 element copy-of
> > > xsl:copy-of : could not compile select expression '$title'
> > > XPath error : Undefined variable
> > > $html.stylesheet != ''
> >
> > Is that after applying Martin's docbook patches yesterday?
> > (I haven't tested that yet.)
>
> Unless they're in a very recent -linus. Probably this is a sign to test
> those patches. :-)
but I don't remember doing anything to the HTML generation part.
perhaps you need newer stylesheets? I have docbook-xsl 1.68.1 here.
if the problem persists for you, could you hand me a copy of the
your stylesheet for testing? It would be nice if kernel-doc would
work with more versions than mine ;-)
--
Martin Waitz