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
