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

Question

我正在做另一个PHP框架，它的乐趣和运动，我正在做第一轮文档。我打算编写一些代码，记录我编码的内容，编写更多代码，调整文档以反映代码的新功能，重复。例如，配置目前非常手动且繁琐，但我记录它，因为它需要像今天一样进行配置。一旦我达到自动化设置的目的，我就打算重写这些部分，以反映当前的状态。

我想知道的是，是否有任何启发式方法可以使参考文档保持最新状态？我不是只是谈论记录API（哪种免费提供PHPDoc等），还有更大的方案;教程，概述 - 文章 - 一切。有没有什么好方法可以最大限度地减少忘记更新特殊内容的机会？

Answer 1

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

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

文档应用程序将测试日期差异（在更高版本中，与我们的源代码控制相比），并在怀疑不匹配时会发出警告标志。

在PHP中，如果它们以预先知道的方便格式保存，那么构建一些东西来扫描代码备注应该不会太难。

Answer 2

由于非本地化，这是一个非常困难的问题：一个文档元素中的信息可能依赖于或影响多个代码位置，当您查看代码位置时，您通常不了解文档。因此，代码的更改可能不会触发文档的更新，即使用户本来愿意这样做。

我认为在每个代码部分中包含某种形式的显式链接非常重要，其中更改会触发文档中的更改。让人们更新文本是一段时间，因此让他们找到可能受影响的区域很困难，特别是对于更一般的材料（例如API）

如果我要更新多个位置中提到的功能，我需要该列表至少知道在哪里寻找可能需要更新的内容。