Где поставить глоссарий важных терминов и узоров в документации? [закрыто

Question

Привет.

Я хочу документировать определенные шаблоны в коде, чтобы создать последовательную терминологию (для того, чтобы упростить связь о программном обеспечении). Однако я не уверен, где определить условия. Для того, чтобы получить на одном уровне, пример:

У меня есть генератор кода. Этот генератор кода получает определенную входную настройку от анализатора (да, имя ввода имени может быть меньше идеального). Эта входная настройка затем преобразуется в различные последующие данные (например, абстрактное описание процесса проверки). Каждая из этих факторов может быть либо преобразована в другое значение той же обработки данных или может быть преобразована в следующую таблицу данных. Это должно звучать как трубы и фильтры в некоторой степени.
Учитывая это, я называю операцию, которая принимает данные, которая принимает данные острой и создает значение того же трансформации трансформации, в то время как я вызываю работу, которая принимает Datastructure и производит различную трансмирующую Datastructure вывод. Последний этап вывода строки, содержащего код, называется излучением. (Итак, в целом, Codegenerator принимает входную структуру и преобразовывать, трансформации, происходящие, трансформации, происходят и, наконец, испускают).

Я думаю, что подчеркивающие эти термины будут выгодальными в связи с коммуникациями, потому что тогда легко говорить о вещах. Если вы слышите «преобразование», вы знаете: «Хорошо, мне нужно только подумать об этих двух данных», если вы слышите «излучающие», вы знаете: «Хорошо, мне нужно только узнать эту структуру и целевой язык».

Тем не менее, где я документирую эти шаблоны? Текущая кодовая база использует посетителей и предлагает классы, называемые ValidatortransFormationBaseu003CResultType> (или входнойStructurTrentransformationBaseu003CResultType> И так один и так далее).

Я не очень хочу добавить определение таких терминов на интерфейсы, потому что в этом случае я должен был повторить себя на каждом интерфейсе, который явно нарушает сухость.

Я рассматриваю, чтобы подчеркнуть различие между преобразованиями и производными, добавляя дополнительные интерфейсы (я должен был бы подумать о лучшем имени для классов преобразования, но тогда я мог бы сделать, как видно, что Validatortransformation расширяет вариантрансформацияu003CValidator> или ValidatorderivationFrominputtructure расширяет входную структуруu003CValidator> ).

Я также думаю, что я должен добавить пользовательскую страницу в документацию Doxygen уже существующую, как в «Глоссарии» или «Принципах архитектуры», которая содержит такие принципы. Единственным недостатком этого будет то, что вкладчик должен будет найти эту страницу, чтобы на самом деле узнать об этом.

Я пропускаю возможности или я сужу что-то не так, по вашему мнению?

С уважением, Tetha

Answer 1

Я видел программный корабль с открытым исходным кодом с Readme-разработчики, readme для разработчиков, которые списки, между другими, такие как глоссарии, RCS, URL для Wikis и так далее.

Answer 2

Вы могли бы приклеить их в package.html Файл внутри пакета, где определены эти интерфейсы. Вы можете пойти до иерархии пакета, как имеет смысл.