From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from saturn.retrosnub.co.uk ([178.18.118.26]:39865 "EHLO saturn.retrosnub.co.uk" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S941715AbdAGTpf (ORCPT ); Sat, 7 Jan 2017 14:45:35 -0500 Subject: Re: [PATCH 00/11] buffer.h cleanup and split To: Lars-Peter Clausen , linux-iio@vger.kernel.org References: <20170102192834.26546-1-jic23@kernel.org> <596ebd84-d281-e8d8-8a7e-b4ee460a4739@metafoo.de> Cc: Daniel Baluta , Hartmut Knaack , Peter Meerwald-Stadler From: Jonathan Cameron Message-ID: <1e5bc993-b630-8646-dd71-f43c83c2c1d9@kernel.org> Date: Sat, 7 Jan 2017 14:45:32 -0500 MIME-Version: 1.0 In-Reply-To: <596ebd84-d281-e8d8-8a7e-b4ee460a4739@metafoo.de> Content-Type: text/plain; charset=windows-1252 Sender: linux-iio-owner@vger.kernel.org List-Id: linux-iio@vger.kernel.org On 04/01/17 13:41, Lars-Peter Clausen wrote: > On 01/02/2017 08:28 PM, Jonathan Cameron wrote: >> This series came out of the mess that became apparant when looking at the >> autogenerated docs. As we pull the kernel-doc from buffer.h in when >> describing the API the drivers use to access it we were pulling in a lot >> of documentation that was irrelevant to that use case. >> >> Hence, this series does two things: >> 1) Splits the buffer.h header into two parts: >> * buffer.h which just contains the stuff that drivers using buffers need. >> * buffer_impl.h which just contains the stuff related to the implementation >> of buffers >> This makes struct iio_buffer opaque to the drivers (with a few extra >> access functions and a bit of code reorganization) >> 2) Takes the documentation of struct iio_buffer inline, allowing fairly >> sensible use of the private: label within docs rather than our local >> iio specific tagging of documentation. There is an oddity here in that >> I have deliberately 'broken' the kernel-doc for elements that are private >> in order to avoid lots of warnings about excess documentation. >> >> Along the way various drivers gained additional includes that should probably >> have been there in the first place. This was needed to cleanup the includes >> within the includes. Most drivers did it 'right' anyway so this wasn't too >> bad. >> >> I'll probably follow this up with similar cleanups elsewhere at some point. >> >> This was against 4.10-rc1 as that's where I'm working on docs, but should >> go in reasonably cleanly on iio/togreg or iio/testing. > > Looks good. I'm not convinced the split is necessary, but it doesn't hurt > either. Full series: Yeah, bit marginal on necessity but will make the docs rather nice when I (or someone else) gets around to documenting how to write a buffer driver. In the meantime means a lot of irrelevant stuff goes from the driver api docs on using a buffer. > > Reviewed-by: Lars-Peter Clausen > Thanks, Series applied to the togreg branch of iio.git which will get pushed out as testing at somepoint soonish. Jonathan