[Ksummit-discuss] [CORE TOPIC] Documentation

[Daniel Vetter]

On Tue, Aug 4, 2015 at 2:50 PM, Laurent Pinchart
<laurent.pinchart at ideasonboard.com> wrote:
> Hi Jon,
>
> On Monday 03 August 2015 08:33:11 Jonathan Corbet wrote:
>> On Mon, 03 Aug 2015 15:35:36 +0200 Rafael J. Wysocki wrote:
>> > > While I don't discourage it, I am not a fan of automated documentation.
>> > > As you and mtk would know, writing high quality, informative, systems
>> > > software documentation is an involved process. And it should be, imo.
>> > > Same goes for describing APIs and algorithms in code comments. Sure,
>> > > automation has its pros, particularly keeping docs up to date; yet this
>> > > does not outweigh a well crafted document, which involves actual though.
>> >
>> > "thought" I guess?
>> >
>> > I have to say I agree here.
>>
>> Surely nobody thinks I was saying that the documentation-writing process
>> can be automated! :)  But we go to some lengths now to document our APIs
>> in the code; I don't think we would want to break that.
>>
>> > Not to mention the fact that if you are browsing the kernel tree via a web
>> > frontend or LXR, for example, plain text docs are really good to have.
>>
>> The nice thing about formats like Markdown or ReST is that they *are*
>> plain text for all practical purposes.  Much better than DocBook in that
>> regard.
>
> My problem with inline documentation is that it makes easier for developers to
> write crappy doc and believe they've done their duty. It's not a technical
> issue, and I believe inline documentation has merits, especially for API
> documentation, but I've seen too many kerneldoc comments written as
>
> /**
>  * int do_foo_bar(int foo, bool bar) - Do foo bar
>  * @foo: the foo for bar
>  * @bar: the value of bar
>  *
>  * This function does foo bar.
>  *
>  * Return 0 on success and a negative value on error.
>  */
>
> That's just useless. Worse, it can give the impression to reviewers that the
> function has been documented while it clearly hasn't. Maybe we just need to
> tighten the review process and push harder for documentation, at the risk of
> rejecting useful contributions. That's not a new problem though.

Yeah api/struct docs alone aren't enough, that's why you need overview
sections to tie it all together. And in those you really need links to
all the various entry points to be able to digg out the details. Same
goes for api docs themselves, I try to always list related functions
in there so that you can easily jump to more specific functions or
between init/free and similar pairs.

> DocBook and kerneldoc documentation serve two very different purpose in my
> opinion. While kerneldoc mostly aims at documenting internal APIs, DocBook is
> more of a story telling kind of documentation, suitable for documenting
> subsystem architectures for instance. This could be moved to inline comments,
> but at the end of the day I don't think it will make a big difference. The
> reason why we miss quality "background" documentation today has in my opinion
> more to do with the fact that we don't require it.

Yeah pure function docs alone are useless, which is why I always ask
for an intro/overview section.

> A good (or bad example, depending on how you see it) of this is the DRM/KMS
> documentation available from Documentation/DocBook/drm.tmpl. I spent a
> considerable amount of time writing it, it got reviewed, merged in the kernel,
> and has now been rendered completely useless as the DRM/KMS internal API has
> evolved and the documentation hasn't been updated despite my repeated
> requests. That was extremely demotivating, and made me give up documenting
> DRM/KMS at all.

drm having gone downhill is why I want to pull it out of the template
into code. E.g. we have extensive docs for vtables, but since they're
not next to the vtables in the code no one updates those. And
duplicating a summary in kerneldoc and then the extended version in
the docbook is even worse imo.

Also editing docbook is really a major pain imo. The drm docbook file
is currently at over 4k lines, and that's just not something you can
manage any more sensibly.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch