linux-kernel - Re: [PATCH 28/36] docs-rst: convert s390-drivers DocBook to ReST

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20170516061928.14158635@vento.lan>
Date:   Tue, 16 May 2017 06:19:28 -0300
From:   Mauro Carvalho Chehab <mchehab@...pensource.com>
To:     Cornelia Huck <cornelia.huck@...ibm.com>
Cc:     linux-kernel@...r.kernel.org,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        Jonathan Corbet <corbet@....net>,
        Martin Schwidefsky <schwidefsky@...ibm.com>,
        Heiko Carstens <heiko.carstens@...ibm.com>,
        Jani Nikula <jani.nikula@...el.com>,
        Markus Heiser <markus.heiser@...marit.de>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Takashi Iwai <tiwai@...e.de>,
        "Herton R. Krzesinski" <herton@...hat.com>,
        linux-s390@...r.kernel.org
Subject: Re: [PATCH 28/36] docs-rst: convert s390-drivers DocBook to ReST

Em Mon, 15 May 2017 10:09:40 +0200
Cornelia Huck <cornelia.huck@...ibm.com> escreveu:

> On Fri, 12 May 2017 11:00:11 -0300
> Mauro Carvalho Chehab <mchehab@...pensource.com> wrote:
> 
> > Use pandoc to convert documentation to ReST by calling
> > Documentation/sphinx/tmplcvt script.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@...pensource.com>
> > ---
> >  Documentation/DocBook/Makefile            |   2 +-
> >  Documentation/DocBook/s390-drivers.tmpl   | 161 ------------------------------
> >  Documentation/driver-api/index.rst        |   1 +
> >  Documentation/driver-api/s390-drivers.rst | 111 ++++++++++++++++++++
> >  4 files changed, 113 insertions(+), 162 deletions(-)
> >  delete mode 100644 Documentation/DocBook/s390-drivers.tmpl
> >  create mode 100644 Documentation/driver-api/s390-drivers.rst  
> 
> Acked-by: Cornelia Huck <cornelia.huck@...ibm.com>

Thanks!

> 
> ...but I wonder how good the information in there still is, given that
> I haven't touched it in ages...

The text inside it is just a brief description of s390 specifics,
but the real API descriptions are inside those files:

.. kernel-doc:: arch/s390/include/asm/cio.h
.. kernel-doc:: arch/s390/include/asm/ccwdev.h
.. kernel-doc:: drivers/s390/cio/device.c
.. kernel-doc:: drivers/s390/cio/device_ops.c
.. kernel-doc:: arch/s390/include/asm/cmb.h
.. kernel-doc:: drivers/s390/cio/cmf.c
.. kernel-doc:: arch/s390/include/asm/ccwgroup.h
.. kernel-doc:: drivers/s390/cio/ccwgroup.c
.. kernel-doc:: drivers/s390/cio/airq.c

Those 9 files seem to have been updated lately:

$ git log arch/s390/include/asm/cio.h arch/s390/include/asm/ccwdev.h drivers/s390/cio/device.c drivers/s390/cio/device_ops.c arch/s390/include/asm/cmb.h drivers/s390/cio/cmf.c arch/s390/include/asm/ccwgroup.h drivers/s390/cio/ccwgroup.c drivers/s390/cio/airq.c|grep Date
Date:   Fri Mar 17 04:17:42 2017 +0100
Date:   Thu Feb 2 19:15:33 2017 +0100
Date:   Thu Jan 12 18:53:56 2017 +0100
Date:   Sun Oct 30 16:37:24 2016 -0400
Date:   Fri Jul 29 10:43:53 2016 +0200
Date:   Thu Jun 23 11:09:26 2016 +0200
Date:   Tue Jul 12 19:57:57 2016 +0200
Date:   Mon Jun 20 14:03:38 2016 +0200
Date:   Tue May 31 09:09:57 2016 +0200
Date:   Thu Mar 3 20:49:57 2016 -0800
Date:   Fri Dec 18 12:59:36 2015 +0100
Date:   Mon Jun 29 18:39:54 2015 +0200
Date:   Mon Oct 26 12:38:13 2015 +0100
Date:   Mon Oct 26 12:35:06 2015 +0100
Date:   Mon Sep 21 18:40:33 2015 +0200
...

So, I guess that what's there is still valid.

Yet, on a quick grep:

$ git grep -l "/\*\*" drivers/s390/|wc -l
91

So, it seems that only 10% of the kernel-doc markups are actually
documented :-)

Perhaps you could add the missing files there after this patch ;-)


Thanks,
Mauro