您如何保持參考文檔是最新的？

Question

我正在做的另一個PHP框架的樂趣和它的運動，我正在做的第一輪文檔。我打算編寫一些代碼，記錄我編寫的代碼，編寫更多的代碼，調整文檔以反映代碼的新功能，重複一遍。例如，配置目前非常手動且乏味，但我正在記錄它，因爲它需要像今天這樣配置。一旦我達到自動化設置，我正計劃重寫這些部分，以反映當前狀態。

我在想什麼，是否有任何啓發式方法來保持參考文檔是最新的？我不是只是談論關於記錄API（PHPDoc和類似的免費類型），但也是更大的方案;教程，概述 - 文章 - 一切。有沒有什麼好的方法來儘量減少忘記更新特別的東西的機會？

Answer 1

由於離域化，這是一個非常困難的問題：一個文檔元素中的信息可能取決於或影響多個代碼位置，並且當您查看代碼位置時，您通常不知道文檔。因此，即使用戶願意這樣做，代碼中的更改也不會觸發文檔的更新。

我認爲重要的是在每個代碼部分包含某種形式的顯式鏈接，其中一個更改會觸發文檔中的更改。讓人們更新文本是一種延伸，所以讓他們找到可能受到影響的區域是困難的，尤其是對於更一般的材料（例如API）

如果我正在更新中提到的功能幾個地點，我需要這個清單至少有一個想法，在哪裏尋找潛在的需要更新。

Answer 2

我在第一份工作中做了類似的事情。

/* 
<document> 
    <version>x.y.z.g</version> 
    <date>10.4.2009</version> 
    <key>fff#ggg</key> 
    <more...................../more> 
</socument> 
*/ 
int ggg(char x){ 
... 
... 
} 

文檔管理器應用程序將測試日期的差異（和更高版本中，對我們的源代碼控制），並會提高的警告標誌時，懷疑存在不匹配。

在PHP中，如果構建一些代碼來評估代碼，如果它們保留在預先知道的方便格式中，應該不會太難。