Où mettre un glossaire des termes et des modèles importants dans la documentation? [fermé]

Question

Bonjour.

Je veux documenter certains modèles dans le code afin de construire une terminologie cohérente (pour la communication easen sur le logiciel). Je suis, cependant, ne sachant pas où définir les termes donnés. Afin d'obtenir le même niveau, un exemple:

J'ai un générateur de code. Ce générateur de code reçoit un certain InputStructure du Parser (oui, le nom InputStructure peut être inférieur à l'idéal). Cette InputStructure est ensuite transformé en diverses structures de données suivantes (comme une description abstraite du processus de validation). Chacune de ces structures de données peuvent être soit transformé en une autre valeur du même ou il peut structure de données se transformer en la prochaine structure de données. Cela devrait ressembler à tuyaux et filtres à un certain degré.
Compte tenu de cela, j'appelle une opération qui prend un datastructures et construit une valeur de même une transformation structure de données, alors que j'appelle une opération qui prend une structure de données et produit un autre structure de données suivi d'une dérivation. La dernière étape de dérivation d'un code contenant la chaîne d'émission est appelé. (Donc, dans l'ensemble, la CodeGenerator prend la structure d'entrée et se transforme, transforme, dérive, transforme, et enfin dérive) émet.

Je pense que ces termes insiste sur benefitial seront dans les communications, car il est facile de parler de choses. Si vous entendez la « transformation », tu sais « Ok, je ne dois penser à ces deux structures de données », si vous entendez « émettre », tu sais « Ok, je ne ai besoin de connaître cette structure de données et la langue cible. ».

Cependant, où dois-je documenter ces modèles? Les utilisations actuelles base de code visiteurs et propose des cours appelés comme ValidatorTransformationBase (ou InputStructureTransformationBase , et ainsi et ainsi de suite).

Je ne veux pas vraiment ajouter la définition de ces termes aux interfaces, parce que dans ce cas, je dois me répéter sur chaque interface, ce qui constitue une violation flagrante DRY.

J'envisage de mettre l'accent sur la distinction entre les transformations et Dérivations en ajoutant d'autres interfaces (je dois penser à un meilleur nom pour les TransformationBase classes, mais je pouvais faire pense comme extends ValidatorTransformation ValidatorTransformationBase ou ValidatorDerivationFromInputStructure étend InputStructureTransformation ).

Je pense aussi que je devrais ajouter une page personnalisée à la documentation doxygen déjà existante, comme dans « Glossaire » ou « Principes d'architecture », qui contient ces principes. Le seul inconvénient de ce serait qu'un contributeur devra trouver cette page pour apprendre réellement à ce sujet.

Suis-je manque de possibilités ou suis-je juger quelque chose de mal ici, à votre avis?

- Cordialement, Tetha

Answer 1

J'ai vu des navires de logiciel libre avec README-développeurs , un readme pour les développeurs qui listes, d'autres de amongs, des choses telles que glossaires, RCS, urls pour les wikis et ainsi de suite.

Answer 2

Vous pouvez les coller dans un fichier package.html à l'intérieur du paquet où ces interfaces sont définies. Vous pouvez aller aussi loin dans la hiérarchie de paquets sens.