[Intel-gfx] [RFC] Documentation requirements for drm/i915 feature work

[Daniel Vetter]

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