在哪里可以在文档中列出重要术语和模式的词汇表？ [关闭

Question

问候。

我想记录代码中的某些模式，以建立一个一致的术语（以减轻有关软件的通信）。但是，我不确定在哪里定义给定的术语。为了达到同一级别，一个例子：

我有一个代码生成器。该代码生成器从解析器接收一定的输入结构（是的，名称输入结构可能不太理想）。然后将此输入结构转换为各种后续数据架构（例如验证过程的抽象描述）。这些数据架构中的每一个都可以转换为同一数据架构的另一个值，也可以将其转换为下一个数据架构。这听起来像是管道和过滤器。
鉴于此，我调用一个操作，该操作采用数据架构并构造相同数据架构的值一个转换，而我调用一个操作，该操作是进行数据架构并生成不同的后续数据架构A派生。派生包含代码的字符串的最后一步称为发射。 （因此，总的来说，代码加工机采取输入结构和变换，变换，衍生，变换，派生并最终发射）。

我认为强调这些术语在沟通中将是有益的，因为那时就很容易谈论事情。如果您听到“转换”，您就会知道“好的，我只需要考虑这两个数据架构”，如果您听到“发射”，您就知道“好的，我只需要知道这种数据构架和目标语言。”。

但是，我在哪里记录这些模式？当前的代码库使用访问者，并提供称为诸如验证transformationbase的类u003CResultType>（或InputStructurentransFormationBaseu003CResultType> ，所以一个等等）。

我真的不想将这种术语的定义添加到接口中，因为在这种情况下，我必须在每个界面上重复自己，这显然违反了干燥。

我正在考虑通过添加进一步的界面来强调转换和派生之间的区别（我必须考虑转换基类别的更好的名称，但是然后我可以认为诸如validatorTransFormation之类u003CValidator>，或验证范围内引导结构扩展InputStructurentransformationu003CValidator> ）。

我还认为我应该在已经存在的Doxygen文档中添加自定义页面，例如“词汇表”或“架构原则”，其中包含此类原则。唯一的缺点是，贡献者需要找到此页面才能实际了解这一点。

我认为我认为我认为有什么不对劲吗？

- tetha的问候

Answer 1

我已经看到了一些开源软件船 README开发人员, 这是针对开发人员的读书文件，列出了其他内容，例如词汇表，RCS，Wikis的URL等。

Answer 2

你可以把它们粘在 package.html 在包装中定义这些接口的包中的文件。您可以走到包裹层次结构的远处。