Re: [PATCH 2/2] extcon: Add new extcon_register_notifier_all() to monitor all external connectors

[Chanwoo Choi]

On 2017ë 03ì 30ì 19:42, Andy Shevchenko wrote:
> On Thu, Mar 30, 2017 at 12:24 PM, Chanwoo Choi <cw00.choi@xxxxxxxxxxx> wrote:
>> On 2017ë 03ì 30ì 18:05, Andy Shevchenko wrote:
>>> On Thu, Mar 30, 2017 at 11:39 AM, Chanwoo Choi <cw00.choi@xxxxxxxxxxx> wrote:
>>>> The extcon core already provides the extcon_register_notifier() function
>>>> in order to register the notifier block which is used to monitor
>>>> the status change for the specific external connector such as EXTCON_USB,
>>>> EXTCON_USB_HOST and so on. The extcon consumer uses the this function.
>>>>
>>>> The extcon consumer may need to monitor the all supported external
>>>> connectors from the extcon device. In this case, The extcon consumer
>>>> should have each notifier_block structure for each external connector.
>>>>
>>>> This patch adds the new extcon_register_notifier_all() function
>>>> that extcon consumer is able to monitor the status change of all
>>>> supported external connectors by using only one notifier_block structure.
>>>>
>>>
>>>> +/**
>>>> + * extcon_register_notifier_all() - Register a notifier block to get the noti
>>>> + *                             of the status change for all supported external
>>>> + *                             connectors from extcon.
>>>> + * @edev:      the extcon device that has the external connecotr.
>>>> + * @nb:                a notifier block to be registered.
>>>> + *
>>>> + * Note that the second parameter given to the callback of nb (val) is
>>>> + * the current state and third parameter is the edev pointer.
>>>> + */
>>>
>>> Have you checked how it looks like in resulting document file (man /
>>> html / ...) ?
>>> My concern is multi-line short function description.
>>>
>>
>> Actually, I didn't consider the document file as you mentioned.
>> Do you think need to add more detailed description?
> 
> What I meant is the quite long line in *short* description (fist line
> heading with function name).
> See Documentation/doc-guide/kernel-doc.rst for the detailed howto.
> 

If you metioned the following guide on Line 111
in the Documentation/doc-guide/kernel-doc.rst,
OK. I'll modify it.

Example kernel-doc function comment::

  /**
   * foobar() - Brief description of foobar.
   * @arg: Description of argument of foobar.
   *
   * Longer description of foobar.
   *
   * Return: Description of return value of foobar.
   */
  int foobar(int arg)

-- 
Best Regards,
Chanwoo Choi
Samsung Electronics