On Fri, Apr 30, 2021 at 07:06:08PM +0800, Alex Shi wrote: > On 2021/4/19 下午9:35, Matthew Wilcox wrote: > > and surely you need a '.. kernel-doc' to have the ':internal:' make sense? > > > > Then, I wonder how useful it is to bring kernel-doc written in English > > into a Chinese document? Wouldn't we be better off admitting that we > > don't provide Chinese documentation for kernel APIs and referring to > > the English documents? > > > > (I would love nothing more than to provide Chinese documentation for > > kernel APIs, but we don't have any kind of system for providing that > > today) > > > > I wouldn't reject the Chinese version of kernel-api, but a bit concern > of the subtle of the doc could be kept in translation. It would be a > big challenge. :) That's a big challenge, to be sure, but logistically, where would we keep it? A concrete example, we have: Documentation/core-api/xarray.rst which has .. kernel-doc:: lib/xarray.c which contains: /** * xas_load() - Load an entry from the XArray (advanced). * @xas: XArray operation state. * ... */ So where do we put the Chinese translations? The kernel-doc is adjacent to the function to "encourage" C programmers to keep the documentation up to date when they change the function. Do we also put the Chinese text in xarray.c? Do we have a magic Documentation/translations/zh_CN/lib/xarray.c which contains the translations of the kernel-doc in lib/xarray.c? Do we then have tooling which notices that the inline documentation in lib/xarray.c has changed and notifies the translator to keep it up-to-date?
