[U-Boot] KernelDoc

[Wolfgang Denk]

Dear Marek,

In message <201209252246.10322.marex at denx.de> you wrote:
> 
> I've had a discussion with Wolfgang just now about U-Boot coding style. I tried 
> using KernelDoc in a patch, which is not part of the U-Boot Coding Style now, 
> thus it was rejected.
> 
> I really like the idea of annotating functions with proper description, thus I 
> would like to ask, can we reach a general agreement and start using kerneldoc in 
> U-Boot to annotate functions and possibly generate documentation? Or shall we 
> use anything else?
> 
> Or any other annotation stuff? Doxygen style? Shall it be optional or mandatory?

Unfortunately the important (to me) part of our discussion is
presented here only in the last half sentence...

The points I was trying to make was this:

 - If we introdue any documentation system, we should do this
   "officially", not sneak it in with some patch here and there.

 - The first thing we should define is what we want to use it for,
   i.  e. the purpose.

 - When introducing something, we should also agree on a policy and
   guidelines how we want to see it used.

Questions that need to be answered include:

- What is the goal we want to acchieve?  Complete documentation of all
  U-Boot code?  Documentation of some sub-system?  ... ?

- Will we make this mandatory?  So that we will reject all new code
  that is not documented according to kernel-doc rules?

- If so, what does that mean for patches that touch existing code?
  If I change the major part of an existing function (without changing
  it's calling interface), am I obligued to add kernel-doc comments?
  If I change the calling interface, must I add documentation then?

- What sort of documentation do we generate?  How can we make clear
  that for a long, long time it will cover only a small fraction of
  the actual code, eventually even parts of some source files?

- Who will be responsible for maintaining the documentation?  For
  making sure it gives a usable result, it looks more or less
  consistent?

- What about internationalization?  Who will do the translations? ;-)

Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
When you die, the first thing you lose is your life. The  next  thing
is the illusions.                       - Terry Pratchett, _Pyramids_