[libvirt] minor doc generation glitch
Looking at http://libvirt.org/html/libvirt-libvirt.html#virDomainShutoffReason as an example, I see several places where there are spurious "*" in the generated documentation. It looks like anywhere we have: typedef enum { VALUE = 0; /* Multi-line * comment */ } virName; that the python generator is not stripping out the '^ *\*?' regex for continued comment lines. My python is a bit too weak to quickly determine a fix, so I'm throwing this out for anyone else who wants an easy bug to fix. -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
On 06/15/2011 01:25 PM, Eric Blake wrote:
Looking at http://libvirt.org/html/libvirt-libvirt.html#virDomainShutoffReason as an example, I see several places where there are spurious "*" in the generated documentation.
Also, http://libvirt.org/html/libvirt-libvirt.html#virTypedParameter is broken, listing 'charfield[length] field' rather than 'char[length] field' or 'char field[length]' for the first member, and completely missing out on the 'union{} value' member. It's okay if the docs don't list structs in C syntax, but whatever syntax it does use should be close enough to figure out the corresponding C syntax without having to read the source header to check for missing struct members. -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
On Wed, Jun 15, 2011 at 03:21:44PM -0600, Eric Blake wrote:
On 06/15/2011 01:25 PM, Eric Blake wrote:
Looking at http://libvirt.org/html/libvirt-libvirt.html#virDomainShutoffReason as an example, I see several places where there are spurious "*" in the generated documentation.
Also, http://libvirt.org/html/libvirt-libvirt.html#virTypedParameter is broken, listing 'charfield[length] field' rather than 'char[length] field' or 'char field[length]' for the first member, and completely missing out on the 'union{} value' member. It's okay if the docs don't list structs in C syntax, but whatever syntax it does use should be close enough to figure out the corresponding C syntax without having to read the source header to check for missing struct members.
I'm fixing those, nearly done ... Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/
On Thu, Jun 16, 2011 at 01:19:47PM +0800, Daniel Veillard wrote:
On Wed, Jun 15, 2011 at 03:21:44PM -0600, Eric Blake wrote:
On 06/15/2011 01:25 PM, Eric Blake wrote:
Looking at http://libvirt.org/html/libvirt-libvirt.html#virDomainShutoffReason as an example, I see several places where there are spurious "*" in the generated documentation.
Also, http://libvirt.org/html/libvirt-libvirt.html#virTypedParameter is broken, listing 'charfield[length] field' rather than 'char[length] field' or 'char field[length]' for the first member, and completely missing out on the 'union{} value' member. It's okay if the docs don't list structs in C syntax, but whatever syntax it does use should be close enough to figure out the corresponding C syntax without having to read the source header to check for missing struct members.
I'm fixing those, nearly done ...
The enclosed patch includes quite a number of fixes - parsing of "long long int" and similar - add parsing of unions within a struct - remove spurious " * " fron comments on structure fields and enums - fix concatenation of base type and name in arrays - extend XSLT to cope with union in structs this is painful to read (this was apinful to write !), have a look at the resulting libvirt-api.xml and generated page, that's the nicest way to validate it :-) Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/
On 06/16/2011 01:56 AM, Daniel Veillard wrote:
I'm fixing those, nearly done ...
The enclosed patch includes quite a number of fixes - parsing of "long long int" and similar - add parsing of unions within a struct - remove spurious " * " fron comments on structure fields and enums - fix concatenation of base type and name in arrays - extend XSLT to cope with union in structs
this is painful to read (this was apinful to write !), have a look at the resulting libvirt-api.xml and generated page, that's the nicest way to validate it :-)
Indeed, that's precisely what I did; the end result is strictly better, so I'm pretty sure the gorp in the parser and xslt that was needed to get us there is correct. ACK. -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
On Tue, Jun 21, 2011 at 02:58:03PM -0600, Eric Blake wrote:
On 06/16/2011 01:56 AM, Daniel Veillard wrote:
I'm fixing those, nearly done ...
The enclosed patch includes quite a number of fixes - parsing of "long long int" and similar - add parsing of unions within a struct - remove spurious " * " fron comments on structure fields and enums - fix concatenation of base type and name in arrays - extend XSLT to cope with union in structs
this is painful to read (this was apinful to write !), have a look at the resulting libvirt-api.xml and generated page, that's the nicest way to validate it :-)
Indeed, that's precisely what I did; the end result is strictly better, so I'm pretty sure the gorp in the parser and xslt that was needed to get us there is correct.
ACK.
thanks, pushed, Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/
participants (2)
-
Daniel Veillard -
Eric Blake