.. SPDX-License-Identifier: GPL-2.0 .. include:: ../disclaimer-zh_CN.rst :Original: Documentation/doc-guide/contributing.rst :译者: å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> å¦‚ä½•å¸®åŠ©æ”¹è¿›å†…æ ¸æ–‡æ¡£ ==================== 在任何软件开å‘项目ä¸ï¼Œæ–‡æ¡£éƒ½æ˜¯é‡è¦ç»„æˆéƒ¨åˆ†ã€‚好的文档有助于引入新的开å‘人员, 并帮助已有的开å‘人员更有效地工作。如果缺少高质é‡çš„文档,大é‡çš„时间就会浪费在 代ç 的逆å‘工程和犯本å¯é¿å…的错误上。 ä¸å¹¸çš„æ˜¯ï¼Œå†…æ ¸çš„æ–‡æ¡£ç›®å‰è¿œè¿œä¸èƒ½æ»¡è¶³æ”¯æŒå¦‚æ¤è§„模和é‡è¦æ€§çš„项目的需è¦ã€‚ 本指å—适用于希望帮助改善这ç§çŠ¶å†µçš„è´¡çŒ®è€…ã€‚å†…æ ¸æ–‡æ¡£çš„æ”¹è¿›å¯ä»¥ç”±å¼€å‘者在ä¸åŒçš„ 技能层级上进行;这也是一æ¡ç›¸å¯¹ç®€å•å¯ä»¥å¸®åŠ©æ‚¨äº†è§£å†…æ ¸è¿‡ç¨‹å¹¶åœ¨ç¤¾åŒºä¸æ‰¾åˆ°ä¸€å¸ä¹‹ 地的路径。下é¢çš„大部分内容是文档维护人员列出的最迫切需è¦å®Œæˆçš„任务。 文档待办事项列表 ---------------- 为了使我们的文档达到应有的水平,需è¦å®Œæˆçš„任务数ä¸èƒœæ•°ã€‚æ¤åˆ—表包å«è®¸å¤šé‡è¦çš„ 项目,但还远远ä¸å¤Ÿè¯¦å°½ï¼›å¦‚果您知é“改进文档的其他方法,请ä¸è¦ç¾žäºŽå¯é½¿ã€‚ 消除è¦å‘Šï¼ˆWARNING) ~~~~~~~~~~~~~~~~~~~ 文档构建目å‰å‡ºçŽ°äº†æ•°é‡æƒŠäººçš„è¦å‘Šã€‚è™±å多了ä¸ç—’,债多了ä¸æ„;大伙儿忽略了它们, 他们永远ä¸ä¼šæ³¨æ„åˆ°ä»–ä»¬çš„å·¥ä½œå¢žåŠ äº†æ–°çš„è¦å‘Šã€‚å› æ¤ï¼Œæ¶ˆé™¤è¦å‘Šæ˜¯æ–‡æ¡£å¾…办事项列表 ä¸ä¼˜å…ˆçº§æœ€é«˜çš„任务之一。这项任务本身相当简å•ï¼Œä½†å¿…须以æ£ç¡®çš„æ–¹å¼è¿›è¡Œï¼Œæ‰èƒ½å– å¾—æˆåŠŸã€‚ C代ç 编译器å‘出的è¦å‘Šå¸¸å¸¸ä¼šè¢«è§†ä¸ºè¯¯æŠ¥ï¼Œä»Žè€Œå¯¼è‡´å‡ºçŽ°äº†æ—¨åœ¨è®©ç¼–译器é—嘴的补ä¸ã€‚ 文档构建ä¸çš„è¦å‘Šå‡ 乎总是指å‘真æ£çš„问题;è¦æ¶ˆé™¤è¿™äº›è¦å‘Šï¼Œéœ€è¦ç†è§£é—®é¢˜å¹¶ä»Žæºå¤´ä¸Š è§£å†³é—®é¢˜ã€‚å› æ¤ï¼Œä¿®å¤æ–‡æ¡£è¦å‘Šçš„è¡¥ä¸ä¸åº”åœ¨æ ‡é¢˜ä¸ç›´æŽ¥å†™â€œä¿®å¤è¦å‘Šâ€ï¼›å®ƒä»¬åº”该指明 真æ£ä¿®å¤çš„问题。 å¦ä¸€ä¸ªé‡ç‚¹æ˜¯ï¼Œæ–‡æ¡£è¦å‘Šå¸¸å¸¸ç”±C代ç 里kernel-doc注释ä¸çš„问题引起。虽然文档维护 人员对收到这些修å¤è¡¥ä¸çš„å‰¯æœ¬è¡¨ç¤ºæ„Ÿè°¢ï¼Œä½†æ˜¯æ–‡æ¡£æ ‘å®žé™…ä¸Šé€šå¸¸å¹¶ä¸é€‚åˆæŽ¥å—这些 è¡¥ä¸ï¼›å®ƒä»¬åº”该被交给相关å系统的维护人员。 例如,在一次文档构建ä¸ï¼Œæˆ‘å‡ ä¹Žæ˜¯éšæ„选å–了一对è¦å‘Š:: ./drivers/devfreq/devfreq.c:1818: warning: bad line: - Resource-managed devfreq_register_notifier() ./drivers/devfreq/devfreq.c:1854: warning: bad line: - Resource-managed devfreq_unregister_notifier() (作了æ–行以便于阅读) 简å•çœ‹ä¸€ä¸‹ä¸Šé¢ç»™å‡ºçš„æºæ–‡ä»¶ï¼Œä¼šå‘çŽ°å‡ ä¸ªkernel-doc注释,如下所示:: /** * devm_devfreq_register_notifier() - Resource-managed devfreq_register_notifier() * @dev: The devfreq user device. (parent of devfreq) * @devfreq: The devfreq object. * @nb: The notifier block to be unregistered. * @list: DEVFREQ_TRANSITION_NOTIFIER. */ 问题在于缺了一个“*â€ï¼Œè¿™ä¸ç¬¦åˆæž„建系统对C注释å—çš„æ ¼å¼è¦æ±‚。æ¤é—®é¢˜è‡ª2016年注释 è¢«æ·»åŠ ä»¥æ¥ä¸€ç›´å˜åœ¨â€”—整整四年之久。修å¤å®ƒåªéœ€è¦æ·»åŠ 丢失的星å·ã€‚看一眼该文件的 历å²è®°å½•ä»¥äº†è§£ä¸»é¢˜è¡Œçš„å¸¸è§„æ ¼å¼æ˜¯ä»€ä¹ˆæ ·ï¼Œå†ä½¿ç”¨ ``scripts/get_maintainer.pl`` æ¥æžæ¸…è°åº”当收到æ¤è¡¥ä¸ã€‚生æˆçš„è¡¥ä¸å¦‚下所示:: [PATCH] PM / devfreq: Fix two malformed kerneldoc comments Two kerneldoc comments in devfreq.c fail to adhere to the required format, resulting in these doc-build warnings: ./drivers/devfreq/devfreq.c:1818: warning: bad line: - Resource-managed devfreq_register_notifier() ./drivers/devfreq/devfreq.c:1854: warning: bad line: - Resource-managed devfreq_unregister_notifier() Add a couple of missing asterisks and make kerneldoc a little happier. Signed-off-by: Jonathan Corbet <corbet@lwn.net> --- drivers/devfreq/devfreq.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/drivers/devfreq/devfreq.c b/drivers/devfreq/devfreq.c index 57f6944d65a6..00c9b80b3d33 100644 --- a/drivers/devfreq/devfreq.c +++ b/drivers/devfreq/devfreq.c @@ -1814,7 +1814,7 @@ static void devm_devfreq_notifier_release(struct device *dev, void *res) /** * devm_devfreq_register_notifier() - - Resource-managed devfreq_register_notifier() + * - Resource-managed devfreq_register_notifier() * @dev: The devfreq user device. (parent of devfreq) * @devfreq: The devfreq object. * @nb: The notifier block to be unregistered. @@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier); /** * devm_devfreq_unregister_notifier() - - Resource-managed devfreq_unregister_notifier() + * - Resource-managed devfreq_unregister_notifier() * @dev: The devfreq user device. (parent of devfreq) * @devfreq: The devfreq object. * @nb: The notifier block to be unregistered. -- 2.24.1 整个过程åªèŠ±äº†å‡ 分钟。当然,我åŽæ¥å‘现有人在å¦ä¸€ä¸ªæ ‘ä¸ä¿®å¤äº†å®ƒï¼Œè¿™äº®å‡ºäº†å¦ä¸€ 个教è®ï¼šåœ¨æ·±å…¥ç ”究问题之å‰ï¼Œä¸€å®šè¦æ£€æŸ¥linux-nextæ ‘ï¼Œçœ‹çœ‹é—®é¢˜æ˜¯å¦å·²ç»ä¿®å¤ã€‚ 其他修å¤å¯èƒ½éœ€è¦æ›´é•¿çš„时间,尤其是那些与缺少文档的结构体æˆå‘˜æˆ–函数å‚数相关的 ä¿®å¤ã€‚è¿™ç§æƒ…况下,需è¦æ‰¾å‡ºè¿™äº›æˆå‘˜æˆ–å‚数的作用,并æ£ç¡®æè¿°å®ƒä»¬ã€‚æ€»ä¹‹ï¼Œè¿™ç§ ä»»åŠ¡æœ‰æ—¶ä¼šæœ‰ç‚¹ä¹å‘³ï¼Œä½†å®ƒéžå¸¸é‡è¦ã€‚如果我们真的å¯ä»¥ä»Žæ–‡æ¡£æž„建ä¸æ¶ˆé™¤è¦å‘Šï¼Œé‚£ä¹ˆ 我们就å¯ä»¥å¼€å§‹æœŸæœ›å¼€å‘人员开始注æ„é¿å…æ·»åŠ æ–°çš„è¦å‘Šäº†ã€‚ “迷失的â€kernel-doc注释 ~~~~~~~~~~~~~~~~~~~~~~ å¼€å‘者被鼓励去为他们的代ç 写kernel-doc注释,但是许多注释从未被引入文档构建。 这使得这些信æ¯æ›´éš¾æ‰¾åˆ°ï¼Œä¾‹å¦‚使Sphinxæ— æ³•ç”ŸæˆæŒ‡å‘该文档的链接。将 ``kernel-doc`` æŒ‡ä»¤æ·»åŠ åˆ°æ–‡æ¡£ä¸ä»¥å¼•å…¥è¿™äº›æ³¨é‡Šå¯ä»¥å¸®åŠ©ç¤¾åŒºèŽ·å¾—为编写注释所åšå·¥ä½œçš„全部价值。 ``scripts/find-unused-docs.sh`` 工具å¯ä»¥ç”¨æ¥æ‰¾åˆ°è¿™äº›è¢«å¿½ç•¥çš„评论。 请注æ„,将导出的函数和数æ®ç»“构引入文档是最有价值的。许多å系统还具有供内部 使用的kernel-doc注释;除éžè¿™äº›æ³¨é‡Šæ”¾åœ¨ä¸“门针对相关å系统开å‘人员的文档ä¸ï¼Œ å¦åˆ™ä¸åº”将其引入文档构建ä¸ã€‚ ä¿®æ£é”™å— ~~~~~~~~ ä¿®å¤æ–‡æ¡£ä¸çš„æŽ’ç‰ˆæˆ–æ ¼å¼é”™è¯¯æ˜¯ä¸€ç§å¿«é€Ÿå¦ä¹ 如何创建和å‘é€ä¿®è¡¥ç¨‹åºçš„方法,也是 一项有用的æœåŠ¡ã€‚我总是愿æ„接å—è¿™æ ·çš„è¡¥ä¸ã€‚这也æ„味ç€ï¼Œä¸€æ—¦ä½ ä¿®å¤äº†ä¸€äº›è¿™ç§ 错误,请考虑转移到更高级的任务,留下一些拼写错误给下一个åˆå¦è€…解决。 请注æ„,有些并 **ä¸æ˜¯** 拼写错误,ä¸åº”该被“修å¤â€ï¼š - å†…æ ¸æ–‡æ¡£ä¸ç”¨ç¾Žå¼å’Œè‹±å¼è‹±è¯æ‹¼å†™çš†å¯ï¼Œæ²¡æœ‰å¿…è¦äº’相倒æ¢ã€‚ - åœ¨å†…æ ¸æ–‡æ¡£ä¸ï¼Œæ²¡å¿…è¦è®¨è®ºå¥ç‚¹åŽé¢åº”è¯¥è·Ÿä¸€ä¸ªè¿˜æ˜¯ä¸¤ä¸ªç©ºæ ¼çš„é—®é¢˜ã€‚å…¶ä»–ä¸€äº›æœ‰ åˆç†åˆ†æ§çš„地方,比如“牛津逗å·â€ï¼Œåœ¨è¿™ä¹Ÿæ˜¯è·‘题的。 与对任何项目的任何补ä¸ä¸€æ ·ï¼Œè¯·è€ƒè™‘您的更改是å¦çœŸçš„让事情å˜å¾—更好。 “上å¤â€æ–‡æ¡£ ~~~~~~~~~~ ä¸€äº›å†…æ ¸æ–‡æ¡£æ˜¯æœ€æ–°çš„ã€è¢«ç»´æŠ¤çš„,并且éžå¸¸æœ‰ç”¨ï¼Œæœ‰äº›æ–‡ä»¶ç¡®å¹¶éžå¦‚æ¤ã€‚å°˜å°ã€é™ˆæ—§ å’Œä¸å‡†ç¡®çš„文档å¯èƒ½ä¼šè¯¯å¯¼è¯»è€…,并对我们的整个文档产生怀疑。任何解决这些问题的 事情都是éžå¸¸å—欢迎的。 æ— è®ºä½•æ—¶å¤„ç†æ–‡æ¡£ï¼Œè¯·è€ƒè™‘它是å¦æ˜¯æœ€æ–°çš„,是å¦éœ€è¦æ›´æ–°ï¼Œæˆ–者是å¦åº”è¯¥å®Œå…¨åˆ é™¤ã€‚ 您å¯ä»¥æ³¨æ„ä»¥ä¸‹å‡ ä¸ªè¦å‘Šæ ‡å¿—: - 对2.xå†…æ ¸çš„å¼•ç”¨ - 指å‘SourceForgeå˜å‚¨åº“ - 历å²è®°å½•é™¤äº†æ‹¼å†™é”™è¯¯å•¥ä¹Ÿæ²¡æœ‰æŒç»å‡ å¹´ - 讨论Git之å‰æ—¶ä»£çš„å·¥ä½œæµ å½“ç„¶ï¼Œæœ€å¥½çš„åŠžæ³•æ˜¯æ›´æ–°æ–‡æ¡£ï¼Œæ·»åŠ æ‰€éœ€çš„ä»»ä½•ä¿¡æ¯ã€‚è¿™æ ·çš„å·¥ä½œé€šå¸¸éœ€è¦ä¸Žç†Ÿæ‚‰ç›¸å…³ å系统的开å‘人员åˆä½œã€‚当有人善æ„地询问开å‘人员,并å¬å–他们的回ç”然åŽé‡‡å– 行动时,开å‘人员通常更愿æ„与这些致力于改进文档的人员åˆä½œã€‚ 有些文档已ç»æ²¡å¸Œæœ›äº†ï¼›ä¾‹å¦‚,我们å¶å°”会å‘现引用了很久以å‰ä»Žå†…æ ¸ä¸åˆ 除的代ç çš„ æ–‡æ¡£ã€‚åˆ é™¤è¿‡æ—¶çš„æ–‡æ¡£ä¼šç¢°è§ä»¤äººæƒŠè®¶çš„é˜»åŠ›ï¼Œä½†æˆ‘ä»¬æ— è®ºå¦‚ä½•éƒ½åº”è¯¥è¿™æ ·åšã€‚æ–‡æ¡£ä¸ å¤šä½™çš„ç²—æžå¤§å¶å¯¹ä»»ä½•äººéƒ½æ²¡æœ‰å¸®åŠ©ã€‚ 如果一个严é‡è¿‡æ—¶çš„文档ä¸å¯èƒ½æœ‰ä¸€äº›æœ‰ç”¨çš„ä¿¡æ¯ï¼Œè€Œæ‚¨åˆæ— 法更新它,那么最好在 å¼€å¤´æ·»åŠ ä¸€ä¸ªè¦å‘Šã€‚建议使用以下文本:: .. warning :: This document is outdated and in need of attention. Please use this information with caution, and please consider sending patches to update it. è¿™æ ·çš„è¯ï¼Œè‡³å°‘我们长期å—苦的读者会得到文件å¯èƒ½ä¼šæŠŠä»–们引入æ§é€”çš„è¦å‘Šã€‚ 文档一致性 ~~~~~~~~~~ 这里的è€å‰è¾ˆä»¬ä¼šè®°å¾—上世纪90年代出现在书架上的Linux书ç±ï¼Œå®ƒä»¬åªæ˜¯ä»Žç½‘上ä¸åŒ ä½ç½®æœæ¥çš„文档文件的集åˆã€‚在æ¤ä¹‹åŽï¼Œï¼ˆå¤§éƒ¨åˆ†ï¼‰è¿™äº›ä¹¦éƒ½å¾—åˆ°äº†æ”¹è¿›ï¼Œä½†æ˜¯å†…æ ¸çš„ 文档ä»ç„¶ä¸»è¦æ˜¯å»ºç«‹åœ¨è¿™ç§æ¨¡åž‹ä¸Šã€‚它有数åƒä¸ªæ–‡ä»¶ï¼Œå‡ 乎æ¯ä¸ªæ–‡ä»¶éƒ½æ˜¯ä¸Žå…¶ä»–文件相 ç‹¬ç«‹ç¼–å†™çš„ã€‚æˆ‘ä»¬æ²¡æœ‰ä¸€ä¸ªè¿žè´¯çš„å†…æ ¸æ–‡æ¡£ï¼›åªæœ‰æ•°åƒä¸ªç‹¬ç«‹çš„文档。 我们一直试图通过编篡一套“书ç±â€æ¥æ”¹å–„è¿™ç§æƒ…况,以为特定读者æä¾›æˆå¥—文档。这 包括: - Documentation/translations/zh_CN/admin-guide/index.rst - Documentation/core-api/index.rst - Documentation/driver-api/index.rst - Documentation/userspace-api/index.rst 以åŠæ–‡æ¡£æœ¬èº«è¿™æœ¬â€œä¹¦â€ã€‚ 将文档移到适当的书ä¸æ˜¯ä¸€é¡¹é‡è¦çš„任务,需è¦ç»§ç»è¿›è¡Œã€‚ä¸è¿‡è¿™é¡¹å·¥ä½œè¿˜æ˜¯æœ‰ä¸€äº› 挑战性。移动文档会给处ç†è¿™äº›æ–‡æ¡£çš„人带æ¥çŸæœŸçš„ç—›è‹¦ï¼›ä»–ä»¬å¯¹è¿™äº›æ›´æ”¹æ— ç”šçƒæƒ… 也是å¯ä»¥ç†è§£çš„。通常情况下,å¯ä»¥å°†ä¸€ä¸ªæ–‡æ¡£ç§»åŠ¨ä¸€ä¸‹ï¼›ä¸è¿‡æˆ‘们真的ä¸æƒ³ä¸€ç›´ç§»åŠ¨ 它们。 å³ä½¿æ‰€æœ‰æ–‡ä»¶éƒ½åœ¨æ£ç¡®çš„ä½ç½®ï¼Œæˆ‘们也åªæ˜¯æŠŠä¸€å¤§å †æ–‡ä»¶å˜æˆä¸€ç¾¤å°å †æ–‡ä»¶ã€‚试图将 所有这些文件组åˆæˆä¸€ä¸ªæ•´ä½“çš„å·¥ä½œå°šæœªå¼€å§‹ã€‚å¦‚æžœä½ å¯¹å¦‚ä½•åœ¨è¿™æ–¹é¢å–得进展有好的 想法,我们将很高兴了解。 æ ·å¼è¡¨ï¼ˆStylesheet)改进 ~~~~~~~~~~~~~~~~~~~~~~~~ éšç€Sphinx的采用,我们得到了比以å‰æ›´å¥½çš„HTML输出。但它ä»ç„¶éœ€è¦å¾ˆå¤§çš„改进; Donald Knuthå’ŒEdward Tufteå¯èƒ½æ˜¯æ˜ åƒå¹³å¹³çš„。这需è¦è°ƒæ•´æˆ‘ä»¬çš„æ ·å¼è¡¨ï¼Œä»¥åˆ›å»º 更具排版效果ã€å¯è®¿é—®æ€§å’Œå¯è¯»æ€§çš„输出。 请注æ„ï¼šå¦‚æžœä½ æ‰¿æ‹…è¿™ä¸ªä»»åŠ¡ï¼Œä½ å°†è¿›å…¥ç»å…¸çš„两难领域。å³ä½¿æ˜¯ç›¸å¯¹æ˜Žæ˜¾çš„å˜åŒ–, 也会有很多æ„è§å’Œè®¨è®ºã€‚唉,这就是我们生活的世界的本质。 æ— LaTeXçš„PDF构建 ~~~~~~~~~~~~~~~~ 对于拥有大é‡æ—¶é—´å’ŒPython技能的人æ¥è¯´ï¼Œè¿™ç»å¯¹æ˜¯ä¸€é¡¹ä¸å¹³å‡¡çš„任务。Sphinx工具链 相对较å°ä¸”包å«è‰¯å¥½ï¼›å¾ˆå®¹æ˜“æ·»åŠ åˆ°å¼€å‘系统ä¸ã€‚但是构建PDF或EPUB输出需è¦å®‰è£… LaTeX,它ç»å¯¹ç§°ä¸ä¸Šå°æˆ–包å«è‰¯å¥½çš„。消除Latex将是一件很好的事情。 最åˆæ˜¯å¸Œæœ›ä½¿ç”¨ `rst2pdf <https://rst2pdf.org/>`_ 工具æ¥ç”ŸæˆPDF,但结果å‘现 æ— æ³•èƒœä»»è¿™é¡¹ä»»åŠ¡ã€‚ä¸è¿‡rst2pdfçš„å¼€å‘工作最近似乎åˆæœ‰äº†èµ·è‰²ï¼Œè¿™æ˜¯ä¸ªå……满希望的 迹象。如果有开å‘人员愿æ„与该项目åˆä½œï¼Œä½¿rst2pdfå¯ä¸Žå†…æ ¸æ–‡æ¡£æž„å»ºä¸€èµ·å·¥ä½œï¼Œ 大家会éžå¸¸æ„Ÿæ¿€ã€‚ 编写更多文档 ~~~~~~~~~~~~ å½“ç„¶ï¼Œå†…æ ¸ä¸è®¸å¤šéƒ¨åˆ†çš„文档严é‡ä¸è¶³ã€‚å¦‚æžœæ‚¨æœ‰ç¼–å†™ä¸€ä¸ªç‰¹å®šå†…æ ¸å系统文档的相应 知识并愿æ„è¿™æ ·åšï¼Œè¯·ä¸è¦çŠ¹è±«ï¼Œç¼–写并å‘å†…æ ¸è´¡çŒ®ç»“æžœå§ï¼æ•°ä¸æ¸…çš„å†…æ ¸å¼€å‘人员和 ç”¨æˆ·ä¼šæ„Ÿè°¢ä½ ã€‚