Re: [Lf_kernel_messages] Re: [RFC/PATCH] Documentation of kernel messages

["Kunai, Takashi" <kunai@linux-foundation.jp>]

Hi Michael,

I initiated this discussion in The Linux Foundation Summit@Google Campus
last week from the viewpoint of requirements by Japanese vendors/users.

As for a file to store message descriptions, I perfectly agree with your
analysis and we also noticed some (+) and (-) you pointed out in the
meeting last week. Our conclusion was to have a file outside of the
kernel source codes to lessen developers burdens and to encourage better
documentations of descriptions (as Andrew mentioned in his initial message).

Takashi Kunai,
The Linux Foundation Japan

holzheu wrote:
> Hi Gerrit,
> 
> The common thing of your and our approach is, that we need an ID to
> identify a message either by:
> 
> * Using hashes + component name (maybe)
> * Or using hand-made message numbers + component name. Numbers have
>   to be unique within the kernel component
> 
> I think the main difference of your approach is, that documentation will
> be maintained outside the kernel. This has advantages, but also
> disadvantages:
> 
> (+) Developers have less work to do :-)
> (+) Kernel sources and patches have less lines of code, since message
>     descriptions are not contained in the kernel sources.
> (+) You can support multiple languages
> 
> (-) Hard to keep printks and descriptions up-to-date. If using hashes,
>     each typo fix in a printk breaks the link to your documentation.
> (-) Since the developer knows the meaning of a printk best, he probably
>     would be the right person to write the description.
> (-) For every Distribution or vanilla kernel you probably need separate
>     external message databases.
> 
> I like the fact, that every printk gets an ID in your approach and you
> do not need additional printk macros.
> 
> Maybe both approaches are not mutually exclusive. If developers would
> like to document their messages within the kernel sources, they still
> could use kernel-doc and our KMSG_DOC macro do do that.
> 
> I admit, that I am not sure about the the best solution here.
> 
> Michael
> 
> 
> _______________________________________________
> Lf_kernel_messages mailing list
> Lf_kernel_messages@lists.linux-foundation.org
> https://lists.linux-foundation.org/mailman/listinfo/lf_kernel_messages
> 
> 


-- 
Kunai, Takashi
The Linux Foundation Japan (New since '07/2/5)
Shibuya Mark City West 22nd Floor
1-12-1 Dogenzaka,Shibuya-ku,Tokyo,Japan
zip150-0043 tel+81-3-4360-5493