0

我正在做另一个 PHP 框架，因为它的乐趣和运动，我正在做第一轮文档。我打算编写一些代码，记录我编写的代码，再编写一些代码，调整文档以反映代码的新功能，然后重复。例如，目前配置非常手动且乏味，但我正在记录它，因为它需要像今天一样配置。一旦我将设置自动化，我计划重写这些部分，以反映当前状态。

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

4

2 回答 2

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 中，构建一些东西来扫描代码注释应该不会太难，如果它们以预先知道的、方便的格式保存的话。

于 2009-04-11T00:07:46.033 回答
1

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

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

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

于 2009-04-10T23:13:25.680 回答