Projet mkd/mkd/Aide

De Wiki EELL.

Exemple d'utilisation

Fichiers de fonctions

Quand c'est possible on écrit chaque fonction d'une application dans un fichier séparé.
Quand les fonctions sont regroupées dans un même fichier, la documentation des fonction apparaîtra dans le même ordre que dans le fichier.

Dans le fichier de la fonction on précise sa syntaxe d'utilisation (header) et son usage.

Exemple pour la fonction cpp_ : dans le fichier cpp_.c

/*D 
	fonction cpp_
 -----------------------------------------------------------------------------
 ACTION:
	La fonction cpp_ lit le fichier source (pnfile) qui est transmis en 
	paramètre et décode les lignes de commentaires précodés dans le style C++ 
	puis les transcrit dans le fichier de destination (pfdoc) lorsque le code 
	correspond à un des codes externes à la fonction; 
	Les variables globales sont les codes et les options.
	Les codes, tabeau de 5 caractères: 
		extern char codes[]; 
		ils doivent être définis dans le programme d'appel:
		char codes[5] = {0,0,0,0,0};
	Les options, n,s,t,v.
		extern unsigned char n,s,t,v;
		elles doivent définies dans le programme d'appel:
		unsigned char n=0,s=0,t=0,v=0;
	Avec les options :
	n: La transcription est précédée du numéro de ligne. Ceci permet 
		d'atteindre facilement la ligne commentée.
	t: Avec l'option t seul le texte commenté est recopié.
		Sans l'option t le commentaire est entièrement recopié.
		Cette option t permet donc de générer des documents directement 
		exploitables ou publiables.
	s: ajoute le commentaire à l'écran et permet les redirections > , >> ,
           ou || etc.
	v: mode bavard
	Remarque :
	Si la détection d'un commentaire à transcrire commence par le caractère '/'
	suivi de '*' il sera transcrit jusqu'à rencontrer le caractère '*' suivi 
	de '/', quel que soit le commentaire ligne inclus dans ce commentaire.
	Si la détection d'un commentaire commence par deux caractères '/', le 
	commentaire sera copié jusqu'au prochain retour à la ligne (NL) ou fin de
	fichier (EOF).
	Ces dispositions facilitent la génération automatique des fichiers 
	d'entête fichier.h ou .hpp etc.

 SYNTAXE:
	#include "version.h"
	#include "cpp_.h"
	int cpp_(FILE *pfdoc, FILE *pnfile);

 PORTABILITE:
	Microsoft Visual studio sous Windows : x86(Win32) x64(Win32 et WIN64)
	gcc sous Unix/Linux.

 DESCRIPTION:
	cpp_ fonction
	FILE* pfdoc: pointeur sur le fichier de destination ouvert par le 
	programme appelant.
	FILE* pnfile: pointeur sur le fichier source ouvert par le programme
	appelant

 VALEUR RETOURNEE:
	Retourne 0 en cas de succès.

 DROIT DE COPIE: (précisé dans version.h) :
*/

/*H  
	// cpp_.c:
	extern int cpp_ (FILE *pfdoc, FILE *pnfile);
*/

Fichiers de commande et Makefile

Toutes les chemins des fichiers de l'application sont regroupés dans un fichier de projet dans l'ordre alphabétique.

Exemple : "ls -1 *.c > app.prj" qui va contenir le nom de tous les fichiers à examiner pour générer la documentation. Attention, ls -1 (chiffre un) et non -l (lettre 'l')

Dnas les exemples suivant on utilise les caractères H et D pour générer la documentation.
Il est d'usage d'utiliser:

• D ou F pour générer le fichier documentaire des fonctions
• G pour la documentation générale
• H pour générer le fichier d'entête (Header)
• P pour les documentations programmeurs (cycle en V)
• U Documentation destinée aux utilisateurs
• e pour une note en anglais
• f pour une note en français
• w pour les warnings

Tous les caractères ASCII sont utilisables, lettres et chiffres.

La ligne de commande "mkd -Cjt H app.prj app.h"
génère le fichier d'entête de toutes les fonctions de l'application.

La ligne de commande "mkd -Cjt D app.prj app_functions.documentation"
génère le fichier de la documentation des fonctions de l'application.

Exemple de lignes dans un Makefile.
Dans cet exemple le Makefile se trouve dans le répertoire des fichiers sources du projet.

APP = MyProgram # This is any "macro"

Create_header_and_functions-doc: # here, this is any unconditional directive. 
     if [ -e "/usr/bin/mkd" ]; \ # Warning: the first char is a tabulation and not spaces
     then \
          ls -1 *.cpp > $APP.prj; \       # first create or overwrite new project file
          mkd -Ctw H $APP.prj $APP.h: \   # create or overwrite header file
          mkd -Ctw D $APP.prj $APP.txt: \ # create or overwrite functions documentation
          mkd -Cwn w $APP.prj $APP.wars; \# create or overwrite warnind documentation for programmers
     else \
          @echo "The mkd command is not installed in bin directory"; \
     fi