您如何保持参考文档是最新的？

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中，如果构建一些代码来评估代码，如果它们保留在预先知道的方便格式中，应该不会太难。