[U-Boot] [PATCH 2/3] image: move all function comments to header file

[Simon Glass]

Hi,

On 15 August 2014 16:56, Bryan Wu <cooloney at gmail.com> wrote:
> On Fri, Aug 15, 2014 at 3:25 PM, York Sun <yorksun at freescale.com> wrote:
>> On 08/15/2014 03:14 PM, Stephen Warren wrote:
>>> On 08/15/2014 04:11 PM, Bryan Wu wrote:
>>>> On Fri, Aug 15, 2014 at 3:10 PM, York Sun <yorksun at freescale.com> wrote:
>>>>> On 08/15/2014 03:07 PM, Bryan Wu wrote:
>>>>>> On Fri, Aug 15, 2014 at 3:01 PM, Jeroen Hofstee <dasuboot at myspectrum.nl> wrote:
>>>>>>> Hello Bryan,
>>>>>>>
>>>>>>>
>>>>>>> On 15-08-14 22:55, Bryan Wu wrote:
>>>>>>>>
>>>>>>>> Several functions comments are C file with function definition, they
>>>>>>>> should be moved to header file with function declaration.
>>>>>>>>
>>>>>>>> Also update genimg_get_kernel_addr() comments for CONFIG_FIT case.
>>>>>>>>
>>>>>>>> Signed-off-by: Bryan Wu <pengw at nvidia.com>
>>>>>>>>
>>>>>>>
>>>>>>> Why _should_ this be done. In general I would not do it
>>>>>>> to keep comment and implementation close to each other.
>>>>>>> (In the hope they actually match). Doxygen and likely the
>>>>>>> kernel doc thing can pick this up. The only reason I can
>>>>>>> think of this being useful is for proprietary code with a public
>>>>>>> api, but this is not applicable for u-boot.
>>>>>>>
>>>>>>
>>>>>> I was asked to do that by Simon and right now in image.c and image.h
>>>>>> it's quite mix.
>>>>>> Some of them are in C code with implementation others are in header
>>>>>> file with declaration.
>>>>>>
>>>>>> I was confused by this in u-boot, although in kernel we put comments
>>>>>> in C code with implementation.
>>>>>>
>>>>>
>>>>> I prefer to see comments near the implementations.
>>>>>
>>>>
>>>> Then we need another patch to move those comments from header file to C file.
>>>
>>> Well, I wouldn't do anything just yet. Simon and York need to sort out
>>> an agreement first, so we don't just keep writing patches that move
>>> stuff back and forth.
>>>
>> I don't have strong opinion for this case. I would prefer to have the comments
>> near the implementation. I understand current code may have mixed style here and
>> there. Unless it is a clean up effort, I wouldn't add such patch to a set with
>> function change or bug fix.
>>
>
> Sure, let's sort out the style firstly and patch is easy to move
> stuff. I will folder the comment change of my genimg_get_kernel_addr()
> to Patch 1/3 then. and let's ignore this one now.

My point is that the implementation is just that, and shouldn't need
to be consulting for people wanting to call the API. By putting the
function comments in the header you can read through the API in one
place. As we add more comments into header files, it should be
possible to leave the implementation file as a 'detail', only for
those digging deeply.

Static functions should still be commented in the C files, since they
don't form part of the API.

Regards,
Simon