协议或接口描述工具

Question

我们必须开发一个协议，作为不同公司不同系统之间的接口描述。实现将由每个公司的开发人员以不同的语言(不知道)进行。

但是，我们希望在文本描述的基础上共同开发该协议。我将有当前版本的基本副本，并希望发送给所有的评论。

，什么是这样做的好工具？

目前，我们正在使用MS Word，这会导致以下几个问题：

• 我们需要大量的时间来格式化文本。
• 不可能在方法描述中引用数据类型。
• 不同章节(不同作者)的措辞不同，很难对齐。

完美的是：

• 具有词汇表和自动完成功能的工具.
• 对其他项的引用(方法、数据类型、.)有活动链接。
• 自动生成可读的(PDF-)文档。

你知道这样的工具吗？

PS:我没有让来做这项工作。也许也暗示了这件事？

Answer 1

这是一个非常大的问题，因为您可能(应该)希望在协议规范中记录许多可能的方面。其中最重要的两个是数据结构和消息序列，其次是错误管理、认证、定时等。

UML当然可以用来描述这些事情，而Enterprise非常能够从模型中生成多功能文档--它肯定有助于解决您的参考问题。但是首先，您必须非常严格地确定如何对协议的每个方面进行建模，然后您将需要构建必要的EA配置/适应。

为了从EA中获得高质量的文档，我建议使用对象模型的DocumentGenerator类来生成文档，因为这比传统的RTF生成器提供了更大的灵活性。首先，除了EA的API之外，您还可以访问Word的API，因此对文档所做的工作远远超过仅使用EA的API。

在不知道您的协议的大小或复杂性的情况下，我要说，这至少需要几个星期的工作，才能让一个有经验的人编写EA适应。但是，如果您的项目范围如此之广，涉及多家公司，则可能值得进行投资。