Hi all, So I guess people have seen the writing on the wall since a while ;-) So with my latest drm kerneldoc series we'll have fairly nice interface docs for most of the still relevant drm core subsystems. Which means we can finally start to look at our own driver. I've already started with a very basic skeleton as part of my latest kerneldoc series, see http://people.freedesktop.org/~danvet/drm/drmI915.html Now we only need to flesh this out! I see three areas where decent documentation provides good value: 1) High level overviews of a feature, i.e. what I've done thus far in my blog posts. 2) Detailed in-driver api documentation as kerneldoc. 3) Documentating userspace ABIs like ioctls structures&flags, properties and so on. I have no idea how to do 3) well, see e.g. the discussion on documenting drm properties. And the drm core is completely undocumented in that area anyway afaik. So I think we can postpone this for now. For now I want to concentrate on 1) and the essentials of 2). For the overview I think it's best to put that directly into the code as extended comments. To also have it in the DocBook we can pull it in as a "DOC:" section into a reference chapter. The overview section should explain key concepts of the feature and also mention relevant functions and interfaces. Not all of them of course, just some pointers to get the reader started with the more in-depth API documentation. For the kerneldoc I think we should just document the important functions which are used all across the driver, or those functions which are central to the implemented code flow. Two examples: - For the runtime pm functions all the generic get/put functions should be documented, plus maybe the core power domain structure. - For full ppgtt the important piece is imo the overview documentation explaining vmas and surrounding concepts. Documenting the low-level platform specific ppgtt functions seems less useless. But the main vma_bind/unbind and pin/unpin functions could be used to explain some of the tricky details (like the PIN_* flags recently introduced). So that's the area I'd concentrate. The kerneldoc must then be pulled into the DocBook next to the relevant overview section to have everything neatly tied together. The simplest way to accomplish this is to pull in all kerneldoc from a given file. Which means a sensible source code split will be even more important henceforth - which is also why I've restructured our Makefile. Note that the kerneldoc+DocBook tooling we have has one thing in common with every other documentation toolchain: It sucks. It sucks specifically (and imo more than necessary) in the following areas: - DocBook is horrible, but unfortunately the only means to create tables and similar things. kerneldoc sections themselves don't really have any fancy formatting. Personally I'd love to see someone implement markdown support for it. - There's no way to hyperlink other sections. Which sucks since people can't click onto the function names in the overview sections. It also doesn't work in any automatic fashion afaik when using DocBook directly instead of kerneldoc. To sum my expectations about drm/i915 driver feature documentation: 1. Create a new section in the drm/i915 DocBook for your feature. Don't go deeper than sect2 - the kernel's DocBook stylesheet will not generate chapter listings for sect3 and deeper, which means no one will be able to find your function references :( 2. Write overview sections as kerneldoc directly in the code at suitable places (maybe split it up if it makes more sense) and pull this into your new DocBook section. 3. Write kerneldoc API headers for the key functions and again pull this into your new DocBook section as reference material. Of course once we have a pile of such documentation I expect that patch series will keep them up to date. The first two features I want to test-drive this with are full ppgtt and the rather recent runtime pm infrastructure. But this will be a general merge requirement in the future. Comments, clarfications, ideas and general feedback highly welcome. Cheers, Daniel -- Daniel Vetter Software Engineer, Intel Corporation +41 (0) 79 365 57 48 - http://blog.ffwll.ch _______________________________________________ Intel-gfx mailing list Intel-gfx@xxxxxxxxxxxxxxxxxxxxx http://lists.freedesktop.org/mailman/listinfo/intel-gfx
