如何幫助改進核心文件¶
文件是任何軟體開發專案的重要組成部分。良好的文件有助於引入新的開發者，並幫助已有的開發者更有效地工作。如果沒有高質量的文件，大量時間將被浪費在逆向工程程式碼和避免可避免的錯誤上。
不幸的是，核心的文件目前遠遠達不到支援如此規模和重要性的專案所需的要求。
本指南適用於希望改善這種狀況的貢獻者。核心文件的改進可以由各種技能水平的開發人員完成；這是總體上學習核心流程並在社群中找到一席之地的相對簡單的方法。以下內容的大部分是文件維護人員最迫切需要完成的任務列表。
文件 TODO 列表¶
為了使我們的文件達到應有的水平，需要執行的任務清單是無窮無盡的。此列表包含許多重要專案，但遠非詳盡無遺；如果您看到改進文件的不同方法，請不要猶豫！
解決警告¶
文件構建目前會發出令人難以置信的警告數量。當您有那麼多警告時，您可能沒有任何警告；人們會忽略它們，並且永遠不會注意到他們的工作何時添加了新的警告。因此，消除警告是文件 TODO 列表中優先順序最高的任務之一。任務本身相當簡單，但必須以正確的方式進行才能成功。
編譯器為 C 程式碼發出的警告通常可以被視為誤報，導致補丁旨在簡單地讓編譯器閉嘴。來自文件構建的警告幾乎總是指向一個實際問題；消除這些警告需要理解問題並在其源頭解決它。因此，修復文件警告的補丁可能不應在變更日誌標題中說“修復警告”；它們應該指出已修復的實際問題。
另一個重要的一點是，文件警告通常是由 C 程式碼中 kerneldoc 註釋中的問題引起的。雖然文件維護者感謝被複制到這些警告的修復程式，但文件樹通常不是實際執行這些修復程式的正確樹；它們應該傳送給相關子系統的維護者。
例如，在文件構建中，我幾乎隨機抓取了一對警告
./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()
（為了便於閱讀，這些行被拆分了）。
快速檢視上面命名的原始檔，發現了一些如下所示的 kerneldoc 註釋
/**
* 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 告訴我應該收到它的人（將補丁的路徑作為引數傳遞給 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 以檢視問題是否已修復。
其他修復將花費更長的時間，特別是那些與缺少文件的結構成員或函式引數相關的修復。在這種情況下，有必要確定這些成員或引數的作用，並正確描述它們。總的來說，這項任務有時會有點乏味，但它非常重要。如果我們可以真正消除文件構建中的警告，那麼我們可以開始期望開發人員避免新增新的警告。
除了來自常規文件構建的警告之外，您還可以執行 make refcheckdocs 以查詢對不存在的文件檔案的引用。
逐漸消失的 kerneldoc 註釋¶
鼓勵開發人員為他們的程式碼編寫 kerneldoc 註釋，但許多這些註釋永遠不會被拉入文件構建中。這使得這些資訊更難找到，並且，例如，使得 Sphinx 無法生成指向該文件的連結。向文件新增 kernel-doc 指令以引入這些註釋可以幫助社群獲得建立它們所投入的全部價值。
可以使用 scripts/find-unused-docs.sh 工具來查詢這些被忽略的註釋。
請注意，最有價值的是引入匯出函式和資料結構的文件。許多子系統也有供內部使用的 kerneldoc 註釋；除非它們放置在專門針對在相關子系統內工作的開發人員的文件中，否則不應將這些註釋拉入文件構建中。
錯別字修復¶
修復文件中的排版或格式錯誤是弄清楚如何建立和傳送補丁的一種快速方法，並且這是一項有用的服務。我總是願意接受這樣的補丁。也就是說，一旦您修復了一些，請考慮繼續執行更高階的任務，為下一個初學者留下一些錯別字。
請注意，有些東西不是錯別字，不應該被“修復”
核心文件中允許使用美式英語和英式英語拼寫。沒有必要透過將其替換為另一個來修復一個。
句點後是否應跟一個或兩個空格的問題不應在核心文件的上下文中進行討論。其他存在合理分歧的領域，例如“牛津逗號”，在這裡也不相關。
與對任何專案的任何補丁一樣，請考慮您的更改是否真的使事情變得更好。
古老的文件¶
一些核心文件是最新的、經過維護的，並且是有用的。一些文件 ... 不是。塵封的、陳舊的和不準確的文件會誤導讀者，並使人們懷疑我們的文件的整體性。任何可以解決此類問題的事情都非常受歡迎。
每當您處理文件時，請考慮它是否是最新的，是否需要更新，或者是否應該完全刪除。您可以注意以下一些警告訊號
引用 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.
這樣，至少我們長期受苦的讀者已被警告該文件可能會誤導他們。
文件一致性¶
這裡的老前輩會記得 20 世紀 90 年代出現在書架上的 Linux 書籍。它們只是從網上各個位置收集的文件檔案的集合。自那時以來，書籍（大部分）有所改進，但核心的文件仍然主要建立在該模型之上。它由數千個檔案組成，幾乎每個檔案都是與其他檔案隔離編寫的。我們沒有連貫的核心文件，我們有數千個單獨的文件。
我們一直在嘗試透過建立一組為特定讀者分組文件的“書籍”來改善這種情況。這些包括
以及這本關於文件本身的指南。
將文件移動到適當的書籍中是一項重要的任務，需要繼續進行。但是，這項工作存在一些挑戰。移動文件檔案會給使用這些檔案的人帶來短期痛苦；他們對這種變化可以理解地不熱情。通常可以提出一次移動文件的理由；但是，我們真的不想繼續移動它們。
即使所有文件都放在正確的位置，我們也只是設法將一大堆變成一組較小的堆。嘗試將所有這些文件整合到一個整體中的工作尚未開始。如果您對我們如何在這方面取得進展有好的想法，我們將非常樂意聽到它們。
樣式表改進¶
透過採用 Sphinx，我們獲得了比以往更好的 HTML 輸出。但是它仍然可以使用很多改進；Donald Knuth 和 Edward Tufte 會留下深刻印象。這需要調整我們的樣式表，以建立更多排版上合理的、可訪問的且可讀的輸出。
請注意：如果您承擔這項任務，您將進入經典的腳踏車棚領域。即使對於相對明顯的更改，也希望有很多意見和討論。唉，這就是我們生活的世界的本質。
非 LaTeX PDF 構建¶
對於有大量時間和 Python 技能的人來說，這是一項非常重要的任務。Sphinx 工具鏈相對較小且包含良好；很容易新增到開發系統中。但是構建 PDF 或 EPUB 輸出需要安裝 LaTeX，它絕不是小型或包含良好的。消除它將是一件好事。
最初的希望是使用 rst2pdf 工具 (https://rst2pdf.org/) 進行 PDF 生成，但事實證明它無法勝任這項任務。最近，rst2pdf 的開發工作似乎再次活躍起來，這是一個充滿希望的跡象。如果一位積極性足夠的開發人員與該專案合作，使 rst2pdf 與核心文件構建一起工作，那麼世界將永遠感激不盡。
編寫更多文件¶
當然，核心的絕大部分都嚴重缺乏文件。如果您有記錄特定核心子系統的知識和這樣做的願望，請不要猶豫，進行一些編寫並將結果貢獻給核心。無數的核心開發人員和使用者會感謝您。