[libvirt] [PATCH 0/7] documentation improvements - again

[Eric Blake]

On 01/22/2013 07:31 AM, Claudio Bley wrote:
> Hi.
> 
> The first two patches are aimed at avoiding generation of empty
> argument description lists, which might happen if a function has
> no documentation for some argument or its return type.

I'd rather see us fail 'make' if we detect missing documentation, to
force developers to add it in, rather than skipping over the generation.
 I'll review the series to see what we can still push before the 1.0.2
release.

> 
> This was happening with virTypedParams* functions (see 
> https://www.redhat.com/archives/libvir-list/2013-January/msg01428.html)
> 
> Patch #3 is just a small cleanup, since a table is not the right thing
> to use and it looks better in some circumstances.
> 
> Patch #4 sports processing of code blocks embedded into comments.
> 
> Basically, it is similar to markdown syntax, except that you only need
> to indent your code with 2 spaces.
> 
> Patch #5 prepares for the later patches being able to distinguish
> between different <pre> blocks.
> 
> Patch #6 and #7 are pretty much self explanatory, I guess.
> 
> Note, that SHJS's license is GPLv3.

As in, we're adding an (optional) dependency on another build tool, but
the resulting output doesn't change in licensing?  That should be okay,
as long as we gracefully succeed even when SHJS is not present.  But I
guess I'll see when I get to that patch.

> 
> Claudio Bley (7):
>   docs: don't write out empty info attributes for function arguments
>   docs: only generate function argument info for args with a
>     description
>   docs: use a div instead of a 3 column table for undisclosed notices
>   docs: process code blocks similar to markdown
>   docs: add class "description" to div's containing descriptions
>   docs: define style of code blocks inside descriptions
>   docs: syntax highlight code blocks using SHJS
> 
>  docs/apibuild.py      |    8 +-
>  docs/libvirt.css      |    8 ++
>  docs/newapi.xsl       |  209 +++++++++++++++++++++++++++++--------------------
>  docs/page.xsl         |    5 +-
>  docs/sh_c.min.js      |    1 +
>  docs/sh_emacs.min.css |    1 +
>  docs/sh_main.min.js   |    4 +
>  7 files changed, 148 insertions(+), 88 deletions(-)
>  create mode 100644 docs/sh_c.min.js
>  create mode 100644 docs/sh_emacs.min.css
>  create mode 100644 docs/sh_main.min.js
> 

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 621 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20130128/11273fd3/attachment-0001.sig>