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

[Leo Liu]

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.

Thanks Michel, the information is helpful.

Leo

>
>