Pas de python disponible … pas de perl … juste un shell … ca impose parfois de produire pas mal de code en shell … Doxygen … c'est le bien pour documenter (au moins partiellement) du code .. Son problème, c'est que par défaut, il ne gere pas les .sh. bon, bien Ceci étant, doxygen offre la possibilite d'utiliser un programme pour filtrer nos sources et en extraire des tags plus “doxygen compliant”

INPUT                  = scripts/
FILE_PATTERNS          = *.sh

# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
# basis.  Doxygen will compare the file name with each pattern and apply the
# filter if there is a match.  The filters are a list of the form:
# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further
# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER
# is applied to all files.

FILTER_PATTERNS        = *.sh=scripts/bash2doxygen.py

Cette derniere option nous permet de préciser que les fichiers d'extension .sh sont d'abord filtrés par scripts/bash2doxygen.py que voici:

#!/usr/bin/python
import sys

def process_line(line):
    if line.find('###') == 0:
        sys.stdout.write(' * ')
        sys.stdout.write(line[3:])
    off = line.find('function')
    if off == 0:
        sys.stdout.write("*/\nint ")
        line = line[8:]
        line = line.strip()
        print line + "();\n"
        sys.stdout.write("/**")

filename = sys.argv[1]
input_file = open(filename, 'r')
lines = input_file.readlines()
print '/**'
for line in lines[:]:
  process_line(line)
print '*/'

Celui ci traite vos scripts bash, insère toutes les lignes commencant par ### dans des commentaires en C en reperant les fonctions.

Ainsi, le fichier sample.sh suivant :

#!/bin/sh
### @file sample.sh
### Fichier d'exemple
###

... some code ...

### @fcn hello
### Affiche Hello
###
function hello()
{
  echo hello

}
### @doxygen_other_tag
### Blablabla
###

produira cet output que doxygen saura traiter :

/**
 * @file
 * Fichier d'exemple
 */
/** 
 * fcn hello
 * Affiche hello
 */
int hello();
/** 
 * @doxygen_other_tag
 * Blablabla
 */

Bon, le bash2doxygen est basique mais finalement, après avoir cherché sur le net, rien de chez rien. Ceci fera l'affaire en attendant de faire/trouver mieux :)

sh/documenter_son_script.txt · Last modified: 2010/01/12 13:29 (external edit)