[PATCH] drm/amdgpu: add kernel DOC for ioctls in amdgpu_cs.c file

[Michel Dänzer]

On 2018-05-31 08:02 PM, Leo Liu wrote:
> On 05/31/2018 01:04 PM, Michel Dänzer wrote:
>> On 2018-05-31 06:49 PM, Leo Liu wrote:
>>> On 05/31/2018 12:47 PM, Michel Dänzer wrote:
>>>> On 2018-05-31 06:39 PM, Leo Liu wrote:
>>>>> On 05/31/2018 12:30 PM, Michel Dänzer wrote:
>>>>>> On 2018-05-30 08:42 PM, Leo Liu wrote:
>>>>>>> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_cs.c
>>>>>>> b/drivers/gpu/drm/amd/amdgpu/amdgpu_cs.c
>>>>>>> index 12f0d18c6ee8..343ff115cff1 100644
>>>>>>> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_cs.c
>>>>>>> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_cs.c
>>>>>>> @@ -1217,6 +1217,49 @@ static int amdgpu_cs_submit(struct
>>>>>>> amdgpu_cs_parser *p,
>>>>>>>         return 0;
>>>>>>>     }
>>>>>>>     +/**
>>>>>>> + * DOC:  amdgpu_cs_ioctl
>>>>>> DOC comments shouldn't be used for functions, see
>>>>>> Documentation/output/doc-guide/kernel-doc.html#function-documentation
>>>>>>
>>>>> This doc is not for the functions, it's like something in commit
>>>>> message
>>>>> about the details of in/out data, and what is the functionality for
>>>>> this
>>>>> ioctl.
>>>> Data structures should be documented in comments directly above their
>>>> definitions, per
>>>> Documentation/output/doc-guide/kernel-doc.html#structure-union-and-enumeration-documentation
>>>>
>>>>
>>>> . What an ioctl does should be described in the function documentation
>>>> comment above its implementation, as described above.
>>> Then what do you think the kernel doc for ioctl should do?
>> The data structure should be documented in a comment above its
>> definition, and what the ioctl does should be documented in a comment
>> above the function implementing it. The source files need to be hooked
>> up to the amdgpu.rst file.
>>
>> Does that answer your question?
> Sort of. It tells me what should not be in the kernel DOC. I will put
> those details about data and functionalities where they should be.
> And focus on what the ioctl is used for for the kernel DOC section.

I'm afraid I don't see DOC comments being useful for documenting ioctls.
They're for general/overview kind of documentation. For ioctls, the data
structure and function documentation comments should be sufficient. You
can reference a data structure in a function documentation comment like
this:

/**
 * amdgpu_cs_ioctl - ...
 * @...: ...
 *
 * ...
 *
 * The userspace parameters for this ioctl are passed in via
 * &drm_amdgpu_cs.
 *
 * Returns:
 * ...
 */


See e.g. the documentation about i915_gem_get/set_tiling_ioctl in
drivers/gpu/drm/i915/i915_gem_tiling.c.


-- 
Earthling Michel Dänzer               |               http://www.amd.com
Libre software enthusiast             |             Mesa and X developer