问题标签 [documentation]

有没有一种从 Visual Studio XML 输出生成 MSDN 样式文档的简单方法？
我没有足够的耐心来为它设置一个好的 xslt，因为我知道我不是第一个跨过这座桥的人。

另外，我最近尝试设置沙堡，但它确实让我的眼睛交叉。要么我在这个过程中遗漏了一些重要的东西，要么就是太投入了。

我知道有人有一个非常好的非常简单的解决方案。

我在这里重申，因为我认为我的格式使该段落不宜阅读：

我尝试了沙堡，但设置起来非常困难。我真正想到的是更简单的事情。

也就是说，除非我只是不了解沙堡过程。对我来说，仅仅为测试人员提供一些可以使用的好东西，这似乎是一大堆额外的包袱。

我在一个复杂的应用程序上工作，不同的团队在他们自己的模块上工作，并有一定程度的重叠。不久前，我们设置了一个 Mediawiki 实例，部分是在我的提示下。我很难让人们真正使用它，更不用说贡献了。

我可以看到分享信息的很多好处。它至少可以减少我们重新发明轮子的次数。

wiki 不是很结构化，但我不确定这是否是一个问题，只要您可以搜索您需要的内容。

有什么提示吗？

我有一个没有Javadoc 的大型代码库，我想运行一个程序来编写一个包含基本Javadoc 信息的框架（例如，为每个方法的参数写入@param ...），所以我只需要填补剩下的空白。

任何人都知道一个好的解决方案吗？

编辑：

JAutodoc 是我一直在寻找的。它有 Ant 任务、一个 Eclipse 插件，并使用 Velocity 进行模板定义。

就是这样。如果你想记录一个函数或一个类，你可以在定义之后放一个字符串。例如：

但是模块呢？如何记录file.py的作用？

我正在使用 D2007 并尝试使用 HelpInsight 功能（自 D2005 起提供）记录我的源代码。我主要对让 HelpInsight 工具提示正常工作感兴趣。从各种网上冲浪和实验中，我发现了以下内容：

1. 使用三斜杠 (///) 注释样式比其他记录的注释样式更有效。即： {*! comment *}和{! comment }
2. 注释必须在它们所针对的声明之前。在大多数情况下，这意味着将它们放在代码的接口部分。（明显的例外是不能从当前单元外部访问并因此在实现块中声明的类型和函数。）
3. 第一条评论不能针对函数。（即它必须是一个类型 - 或者至少看起来解析器必须在 HelpInsight 功能工作之前看到“type”关键字）

尽管遵循这些“规则”，但有时 Help-insight 只是找不到我写的评论。一个文件不会产生正确的 HelpInsight 工具提示，但如果我将此文件包含在不同的虚拟项目中，它就可以正常工作。

有没有人有其他让 HelpInsight 工作的指示/技巧？

我喜欢用 Doxygen 创建 C 或 PHP 代码的文档。我有一个即将到来的 Python 项目，我想我记得 Python 没有/* .. */注释，并且还有自己的自我文档工具，这似乎是 Python 的文档方式。

由于我熟悉 Doxygen，如何使用它来生成 Python 文档？有什么特别需要我注意的吗？

在 Unix 时代，如果不先阅读手册页，您甚至无法关闭软件。然后是具有一致菜单布局和键盘快捷键的 Mac 和 Windows，但您仍然会在收缩包装盒中看到纸质用户手册，其中描述了应用程序中可能的每一个操作。上网后，帮助文件变成了html文件。

现在使用Web 2.0应用程序，您几乎看不到帮助。即使它在那里，它们也只是描述了一些特定的任务。换句话说，这些应用程序更多地依赖于用户群的常识或不让我思考的因素。

几年前，微软提出了一个叫做归纳用户界面的概念，它基本上告诉程序员在应用程序本身上输入指令，但我不确定这个想法有多受欢迎。

使用 F1 键的帮助文件、用户手册和上下文相关在线帮助是否失效？如果用户无法从 UI 中找到该做什么，我是否失败了？如果没有，我应该提供什么程度的帮助？（适用于桌面和网络应用程序）

编辑：文档/帮助文件如何与敏捷开发方法相结合？例如，开发人员是否应该在 UI 更改之前三思而后行，这可能会使一堆屏幕截图过时？

您是否经常在 API 文档（例如“公共函数的 javadoc”）中看到“值限制”的描述以及经典文档？

注意：我不是在谈论代码中的注释

通过“价值限制”，我的意思是：

• 参数是否可以支持空值（或空字符串，或...）？
• '返回值'可以为空还是保证永远不会为空（或者可以是“空”，或者......）？

样本：

我经常看到的（无法访问源代码）是：

我希望看到的是：

我的观点是：

当我使用带有 getReaderNames() 函数的库时，我通常甚至不需要阅读 API 文档来猜测它的作用。但我需要确定如何使用它。

当我想使用这个函数时，我唯一关心的是：在参数和返回值方面我应该期待什么？这就是我安全设置参数和安全测试返回值所需要知道的全部内容，但我几乎从未在 API 文档中看到此类信息......

编辑：

这可能会影响已检查或未检查异常的使用或不使用。

你怎么看 ？值限制和 API，它们是否属于一起？

在 C# 文档标签中，您可以生成类似于 MSDN 的输出。在类、方法和属性上方的 ///（三斜杠）注释区域内允许使用的标签列表是什么？

有各种文档描述了 Solaris/Linux 上的线程，但现在没有描述 Windows 实现。我对此有过浓厚的兴趣，如此重要的事情（似乎）没有记录在案似乎很奇怪。

线程在不同的操作系统上是不一样的——“一次编写，随处运行”对于线程来说是不正确的。

请参阅http://java.sun.com/docs/hotspot/threads/threads.html