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

[Masahiro YAMADA]

Hi.

I vote for comments near the implementation.

I have been digging into the driver model code recently,
but I have to admit it is unreadable because most of comments
are placed in its header files.
(and I am planning to send a patch to move comments to C sources.)

I really want to know "what does this function do?" and "How is it used?" things
before I start to read the detailed implementation.

If they are written separately, I need to open two windows of my editor,
one for reading the comments in a header file,
the other for reading the implementation in a C source.
I am really unhappy about that.

I guess people often use tag jump utilities.
(I like GNU Global, someone may use ctags/etags, cscope, etc. I don't know..)

Such utilities allow us to jump over to the implementation place.
If comments are not there, we have to look for comments by hand.

I think we should keep in our mind this: source files are much more
read than written.
I believe we put the readers' benefits at the top priority.


-- 
Best Regards
Masahiro Yamada