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

[Michel Dänzer]

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?


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