Re: [RFC/PATCH] Documentation of kernel messages

[holzheu <holzheu@linux.vnet.ibm.com>]

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


-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/