Re: [PATCH v5 2/7] docs/zh_CN: Add translation zh_CN/doc-guide/kernel-doc.rst

["Wu X.C." <bobwxc@email.cn>]

On Tue, Apr 13, 2021 at 03:57:12PM -0600, Jonathan Corbet wrote:
> Wu XiangCheng <bobwxc@email.cn> writes:
> 
> > Add new translation
> >   Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
> >
> > Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
> > Reviewed-by: Yanteng Si <siyanteng@loongson.cn>
> > ---
> >  .../zh_CN/doc-guide/kernel-doc.rst            | 500 ++++++++++++++++++
> >  1 file changed, 500 insertions(+)
> >  create mode 100644 Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
> >
> > diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
> > new file mode 100644
> > index 000000000000..b0427944f8f0
> > --- /dev/null
> > +++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
> > @@ -0,0 +1,500 @@
> > +.. include:: ../disclaimer-zh_CN.rst
> > +
> > +:Original: Documentation/doc-guide/kernel-doc.rst
> > +
> > +:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn>
> > +
> > +编写kernel-doc注释
> > +==================
> > +
> > +Linux内核源文件可以包含kernel-doc格式的结构化文档注释，用以描述代码的函数、
> > +类型和设计。将文档嵌入源文件更容易保持文档最新。
> > +
> > +.. note:: 内核文档格式与javadoc、gtk-doc或Doxygen看似很相似，但由于历史原因，
> > +          实际有着明显的不同。内核源包含成千上万个kernel-doc注释。请坚持遵循
> > +          此处描述的风格。
> > +
> > +.. note:: kernel-doc无法包含Rust代码：请参考
> > +          :ref:`Documentation/rust/docs.rst <rust_docs>`。

Hi Jonathan,

> 
> Note that this reference adds a warning to the docs-next build - this
> translation is evidently against linux-next instead.  The warning will
> eventually go away, but it would be better not to do this if possible.

Yeah, seems rust doc do not merge into docs-next yet. It's quite new.

BTW, I'd like to ask does "git.lwn.net" has a web access like git-web or
cgit... ?

> 
> Also, there is no need for a :ref: here; just say
> "Documentation/rust/docs.rst" and the automarkup code will do the right
> thing.  Yes, that should be changed in the original as well.
> 

I'll send another patch to replace the two refs.

And use "Documentation/rust/docs.rst" will also fix the warning.


Thanks,

Wu X.C.