IBM Streams 4.3.0

Documentation de vos kits d'outils SPL

Vous pouvez utiliser le balisage SPLDOC et la commande spl-make-doc pour générer de la documentation RTF pour vos kits d'outils SPL.

Vous pouvez utiliser un balisage SPLDOC dans les commentaires de code de fichier SPL et les descriptions de fichier modèle associés aux artefacts SPL présents dans un kit d'outils. Ensuite, vous pouvez exécuter la commande spl-make-doc pour générer de la documentation et des images HTML visualisables dans un navigateur. Cette commande génère de la documentation en interprétant le balisage SPLDOC dans le code SPL et les fichiers modèle d'un kit d'outils.

Vous pouvez utiliser la commande spl-make-doc afin de générer de la documentation pour des kits d'outils uniques ou multiples. Ajoutez la documentation générée pour le kit d'outils dans le sous-répertoire doc du kit d'outils.

Vous pouvez baliser et générer la documentation des artefacts SPL suivants dans un kit d'outils :

Des fichiers SPL et leurs composants. Les fichiers SPL se terminent par l'extension .spl et les fichiers en mode mixte SPL se terminent par l'extension .splmm.
Des espaces-noms. Un espace-noms est décrit dans un fichier nommé namespace-info.spl dans le répertoire d'espace-noms d'un kit d'outils.
Des opérateurs primitifs et des fonctions natives. Ces artefacts sont décrits dans des fichiers modèle d'opérateur et de fonction.
Des kits d'outils. Un kit d'outils est décrit dans un fichier info.xml.

Pour préparer la documentation des artefacts de kit d'outils, vous pouvez ajouter le balisage SPLDOC à votre kit d'outils.

Associez des commentaires SPLDOC à chaque fichier SPL, opérateur composite, fonction SPL et type SPL global ou statique.
Ajoutez la description d'espace-noms comme commentaire dans le fichier namespace-info.spl.
Pour les opérateurs primitifs et les fonctions, utilisez le balisage SPLDOC dans les éléments de description des fichiers modèle XML.
Ajoutez des informations de présentation pour le kit d'outils à l'élément description du fichier modèle d'informations de kit d'outils (info.xml) pour le kit d'outils.

Remarque : Bien que souhaitables, les descriptions ne sont pas requises. La commande spl-make-doc génère la documentation qui décrit le contenu et les interfaces d'un kit d'outils même lorsqu'aucune description n'est ajoutée aux fichiers.

Pour obtenir des exemples de documentation de kit d'outils, voir les kits d'outils livrés avec le produit et la documentation générée dans Kits d'outils spécialisés et standard SPL.

Pour fournir la documentation appropriée pour les artefacts suivants, décrivez la fonctionnalité, les entrées attendues et les sorties générées, puis prenez soin d'inclure les informations ci-après.

Opérateurs primitifs

Ajoutez les éléments suivants :

Pour chaque port d'entrée ou de sortie, indiquez s'il a besoin d'un type de flux spécifique ou d'un nom et d'un type d'attribut particulier.
Pour chaque paramètre, répertoriez les types de données et les plages de valeurs acceptés et, le cas échéant, les valeurs par défaut.
Pour chaque port d'entrée qui permet les configurations de fenêtrage, indiquez les conditions dans lesquelles la ponctuation de fenêtre est générée.
Décrivez les conditions dans lesquelles un opérateur peut émettre une exception (par exemple, un opérateur ne peut pas ouvrir un fichier). Des exceptions peuvent être documentées à l'aide de la balise d'annotation SPLDOC @throws.
Ajoutez un exemple d'appel d'opérateur à l'aide des balises <codeTemplates> et <codeTemplate> dans le modèle d'opérateur.

Opérateurs composites

Ajoutez les éléments suivants :

Pour chaque port d'entrée ou de sortie, indiquez s'il a besoin d'un type de flux spécifique ou d'un nom et d'un type d'attribut particulier.
Pour chaque paramètre, répertoriez les types de données et les plages de valeurs acceptés et, le cas échéant, les valeurs par défaut.
Décrivez les éventuelles contraintes de configuration de l'opérateur composite pouvant interagir avec la configuration d'application, telles que les contraintes de partition et de placement d'hôte.
Ajoutez un exemple d'utilisation de l'opérateur composite. Choisissez un exemple qui est un programme SPL complet compilable et exécutable par un tiers. Pour les opérateurs composites structurels, ajoutez une figure illustrant le développement d'opérateur composite généré par l'utilisation de l'opérateur composite.

Kits d'outils

Ajoutez les éléments suivants :

Récapitulatif des modifications: Fournissez une liste de mises à jour au kit d'outils à partir d'une version précédente (le cas échéant). Dans le cadre d'une meilleure pratique, le numéro de version de départ du kit d'outils est 1.0.0 et change de façon incrémentielle selon un format VRM (version, édition et niveau de modification). Les versions de kit d'outils sont spécifiées dans le modèle d'informations de kit d'outils (info.xml).
Présentation: Indiquez une présentation du kit d'outils et de ses artefacts.
Instructions d'installation: Indiquez des instructions expliquant précisément comment télécharger et installer le kit d'outils, ainsi que les éventuelles dépendances requises par l'implémentation de kit d'outils (telles que des bibliothèques).
Artefacts de fichiers d'aide: Documentez la fonction et l'utilisation des outils auxiliaires (par exemple, des scripts) qui sont inclus dans le kit d'outils.
Exemple d'utilisation: Créez un exemple d'une application qui utilise des opérateurs, des opérateurs composites, des fonctions et des types de flux dans le kit d'outils. Choisissez un exemple qui est un programme SPL complet compilable et exécutable par un tiers. Placez les fichiers source pour l'exemple dans un exemple de kit d'outils distinct. Pour documenter l'exemple, utilisez la balise d'annotation SPLDOC @sample dans la description de kit d'outils du fichier modèle d'informations de kit d'outils (info.xml) de l'exemple de kit d'outils et ajoutez des descriptions pour les exemples d'artefact de kit d'outils. Utilisez le balisage de lien SPLDOC pour ajouter des références croisées entre le kit d'outils principal et les exemples de kit d'outils.