Hi,
On 15 August 2014 16:56, Bryan Wu cooloney@gmail.com wrote:
On Fri, Aug 15, 2014 at 3:25 PM, York Sun yorksun@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@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@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@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