| Message ID | 1471878705-3963-3-git-send-email-sumit.semwal@linaro.org |
|---|---|
| State | New |
| Headers | show |
On Tue, 23 Aug 2016 08:01:35 +0200 Daniel Vetter <daniel@ffwll.ch> wrote: > I'm also not too sure about whether dma-buf really should be it's own > subdirectory. It's plucked from the device-drivers.tmpl, I think an > overall device-drivers/ for all the misc subsystems and support code would > be better. Then one toc there, which fans out to either kernel-doc and > overview docs. I'm quite convinced it shouldn't be. If you get a chance, could you have a look at the "RFC: The beginning of a proper driver-api book" series I posted yesterday (yes, I should have copied more of you, sorry)? It shows the direction I would like to go with driver API documentation, and, assuming we go that way, I'd like the dma-buf documentation to fit into that. Thanks, jon
Hi Jon, On 23 August 2016 at 18:38, Jonathan Corbet <corbet@lwn.net> wrote: > On Tue, 23 Aug 2016 08:01:35 +0200 > Daniel Vetter <daniel@ffwll.ch> wrote: > >> I'm also not too sure about whether dma-buf really should be it's own >> subdirectory. It's plucked from the device-drivers.tmpl, I think an >> overall device-drivers/ for all the misc subsystems and support code would >> be better. Then one toc there, which fans out to either kernel-doc and >> overview docs. > > I'm quite convinced it shouldn't be. > > If you get a chance, could you have a look at the "RFC: The beginning of > a proper driver-api book" series I posted yesterday (yes, I should have > copied more of you, sorry)? It shows the direction I would like to go > with driver API documentation, and, assuming we go that way, I'd like the > dma-buf documentation to fit into that. > Thanks for your comments, and direction. I'll rework the patches on top of yours then. I'll have a look at your patches to think about how do we handle API guides / detailed documentation as well. > Thanks, > > jon Best, Sumit.
On Tue, 23 Aug 2016 15:28:55 +0200 Daniel Vetter <daniel@ffwll.ch> wrote: > I think the more interesting story is, what's your plan with all the > other driver related subsystem? Especially the ones which already have > full directories of their own, like e.g. Documentation/gpio/. I think > those should be really part of the infrastructure section (or > something equally high-level), together with other awesome servies > like pwm, regman, irqchip, ... And then there's also the large-scale > subsystems like media or gpu. What's the plan to tie them all > together? Personally I'm leaning towards keeping the existing > directories (where they exist already), but inserting links into the > overall driver-api section. To say I have a plan is to overstate things somewhat... One objective I do have, though, is to declutter Documentation/. Presenting people looking for docs with a 270-file directory is unfriendly to say the least. We don't organize the code that way; the average in the kernel is <... find | wc -l ... > about 15 files/directory, which is rather more manageable. Someday I'd like Documentation/ to look a lot more like the top-level directory. It seems to me that we have a few basic types of stuff here: - Driver API documentation, obviously, is a lot of it, and I would like to organize it better and to move it out of the top-level directory. - Hardware usage information - module parameters, sysfs files, supported hardware information, graphic descriptions of the ancestry of hardware engineers, etc. The readership for this stuff is quite different, and I think it should be separate; often it's intertwined with API information at the moment. - Other usage information - a lot of what's under filesystems/ for example, and more. - Core API documentation. - Kernel development tools - the stuff I started pulling together into the dev-tools/ subdirectory. - How to deal with this unruly mob - SubmittingPatches, CodingStyle, development-process, etc. There's process stuff, and general development documents like volatile-considered-harmful.txt or memory-barriers.txt We can go a long way by organizing this stuff within the formatted documentation, but I really think we need to organize the directory structure as well. I see that as a slow-moving process that will take years, but I do think it's a direction we should go. jon
diff --git a/Documentation/index.rst b/Documentation/index.rst index e0fc72963e87..8d05070122c2 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -14,6 +14,8 @@ Contents: :maxdepth: 2 kernel-documentation + dma-buf/intro + dma-buf/guide media/media_uapi media/media_kapi media/dvb-drivers/index
Include dma-buf sphinx documentation into top level index. Signed-off-by: Sumit Semwal <sumit.semwal@linaro.org> --- Documentation/index.rst | 2 ++ 1 file changed, 2 insertions(+)