linux-kernel - Re: [PATCH] DocBook documentation for IIO

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] [thread-next>] [day] [month] [year] [list]

Date:	Fri, 10 Jul 2015 12:13:54 -0700
From:	Randy Dunlap <rdunlap@...radead.org>
To:	Daniel Baluta <daniel.baluta@...el.com>, jic23@...nel.org
CC:	pmeerw@...erw.net, knaack.h@....de, lars@...afoo.de,
	linux-kernel@...r.kernel.org, linux-iio@...r.kernel.org
Subject: Re: [PATCH] DocBook documentation for IIO

On 07/08/15 05:04, Daniel Baluta wrote:
> In our effort to support vendors writing drivers for their own
> sensors we introduce IIO documentation in DocBook format.
> 
> It documents Industrial I/O core including IIO devices, buffers, triggers and
> triggered buffers. It also offers a short list of online resources
> for the IIO subsystem.
> 
> This is far from being complete any suggestions are welcomed. At a first
> glance we also need to add documentation for events. We are also working
> on auto-generating template drivers based on the type of the IIO sensors.

Hi Daniel,

This is a good start.  Might as well get it merged and keep improving it.

Here are a few nits:

Warning(..//drivers/iio/industrialio-buffer.c:1145): cannot understand function prototype: 'struct iio_demux_table '

>> drop the "()" in the first line:
 * struct iio_demux_table() - table describing demux memcpy ops


In iio_buffer_get() and iio_buffer_put(), change "may be NULL"
to "may be %NULL".

In linux/iio/iio.h, struct iio_chan_spec, the sub-fields of @scan_type confuse
scripts/kernel-doc.  There isn't really a good way to do what you are trying
to do (AFAIK).  The problem is that things like "realbits:" (ending with a colon)
cause kernel-doc to think that that is some special comment and it generates
a separate paragraph for it at the end of the struct.  I changed all of those
colons to hyphens, but then kernel-doc just runs all of those sub-field
comment descriptions together... so I added a ';' at the end of each one, but
it doesn't look nice.


> Generated html files should be available online here http://dbaluta.github.io/
> or you could run make htmldocs in the root of your kernel repo to get them.
> 
> Daniel Baluta (1):
>   DocBook: Add initial documentation for IIO
> 
>  Documentation/DocBook/Makefile |   2 +-
>  Documentation/DocBook/iio.tmpl | 588 +++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 589 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/DocBook/iio.tmpl
> 


-- 
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/