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

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

[Alexey Dobriyan]

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.

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

[Randy.Dunlap]

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

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

[Alexey Dobriyan]

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 != ''
                 ^
		...

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

[Randy.Dunlap]

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

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

[Alexey Dobriyan]

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. :-)

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

[Martin Waitz]

[-- Attachment #1: Type: text/plain, Size: 977 bytes --]

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

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

[patch 0/4] DocBook generation updates

[Martin Waitz]

hoi :)

after some months of silence I finally finished some updates to the
kernel documentation.  Nothing major, mostly fixes and small
improvements.

--
Martin Waitz

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

[Martin Waitz]

[-- Attachment #1: docbook-private-struct-members.patch --]
[-- Type: text/plain, Size: 3627 bytes --]

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>

---
 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

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

[Randy.Dunlap]

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

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

[Martin Waitz]

[-- Attachment #1: Type: text/plain, Size: 431 bytes --]

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

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]