[Intel-gfx] [PATCH 16/16] drm: document drm_auth.c

[Emil Velikov]

On 20 June 2016 at 22:17, Daniel Vetter <daniel at ffwll.ch> wrote:
> On Sat, Jun 18, 2016 at 12:46:38AM +0100, Emil Velikov wrote:
>> On 17 June 2016 at 08:33, Daniel Vetter <daniel.vetter at ffwll.ch> wrote:
>> > @@ -64,16 +73,6 @@ int drm_getmagic(struct drm_device *dev, void *data, struct drm_file *file_priv)
>> >         return ret < 0 ? ret : 0;
>> >  }
>> >
>> > -/**
>> > - * drm_authmagic - Authenticate client with a magic
>> > - * @dev: DRM device to operate on
>> > - * @data: ioctl data containing the drm_auth object
>> > - * @file_priv: DRM file that performs the operation
>> > - *
>> > - * This looks up a DRM client by the passed magic and authenticates it.
>> > - *
>> > - * Returns: 0 on success, negative error code on failure.
>> > - */
>> Why is this and drm_getmagic()'s documetation going away ? Kernel doc
>> isn't restricted to EXPORTED_SYMBOL(s) only, is it ?
>
> No, but imo the documentation for the drm core&helpers should be aimed at
> driver writers. And driver writers can only use EXPORT_SYMBOL stuff (or
> from headers), which is why I think it's good to kick out everything else
> to avoid too much clutter. It's already a daunting thing to get started
> with a new drm driver.
>
> Of course we can keep the comments as normal comments, but for these here
> I didn't see the value.
>
> Also note that this is just for the drm core/helpers. In the i915 driver
> documentation we instead try to document non-static stuff (since that's
> exposed to other parts), but just as a rough guideline. Since often our
> source file split doesn't make that much sense, or is too monolithic.
>
> In both cases the goal is to give a useful guideline to users of a piece
> of code (calling it or otherwise using), not developers changing the
> implementation details themselves.

Indeed... Having this (and similar internal/implementation details) as
the kernel doc will bring volume about something that most devs cannot
and should not care about, and is likely confuse them. If at all, one
could keep them as normal comments. Don't feel to strongly about them,
just wanted to educate myself a bit on the topic (dos and don'ts)

Thanks a million !
Emil