185 lines
6.6 KiB
Plaintext
185 lines
6.6 KiB
Plaintext
|
|
|||
|
|
|
|||
|
|
G u i d e d e M i g r a t i o n
|
|||
|
|
|
|||
|
|
|
|||
|
|
1. Arborescence
|
|||
|
|
|
|||
|
|
Les sources de la nouvelle documentation se trouvent dans :
|
|||
|
|
~/hurricane/documentation/hurricane/doc.new
|
|||
|
|
|
|||
|
|
Elle est intall<6C>e dans :
|
|||
|
|
~/coriolis/Linux.SLA4x/install/share/doc/en/html/hurricane.new
|
|||
|
|
|
|||
|
|
|
|||
|
|
2. Ajout d'un nouveau fichier
|
|||
|
|
|
|||
|
|
Il faut modifier les fichiers de configuration suivants :
|
|||
|
|
|
|||
|
|
2.1 doc.new/doxyfile
|
|||
|
|
|
|||
|
|
Ajouter a la variable INPUT les fichiers ".h" et ".dox" associ<63>s.
|
|||
|
|
Sauf en cas de documentation d'une fonction ou d'un objet enti<74>rement
|
|||
|
|
local au ".cpp" il n'est pas n<>cessaire de l'inclure dans la liste.
|
|||
|
|
Merci de respecter l'indentation et l'alignement pour qu'on y voie
|
|||
|
|
clair.
|
|||
|
|
|
|||
|
|
2.2 doc.new/Makefile.am
|
|||
|
|
|
|||
|
|
Ajouter le fichier de documentation (".dox") uniquement <20> la cible :
|
|||
|
|
doc_en_hurricane_EXTRA
|
|||
|
|
|
|||
|
|
|
|||
|
|
3. Ajout d'une figure
|
|||
|
|
|
|||
|
|
Les figures doivent <20>tre mises dans le sous-r<>pertoire "images", au format
|
|||
|
|
.fig, si possible (sinon png/gif & pdf pour chaque image).
|
|||
|
|
|
|||
|
|
3.1 doc.new/images/Makefile.am
|
|||
|
|
|
|||
|
|
Ajouter le .fig OU les png/gif & pdf <20> la cible EXTRA_DIST.
|
|||
|
|
|
|||
|
|
3.2 doc.new/Makefile.am
|
|||
|
|
|
|||
|
|
Dans le cas des .fig, il faut g<>n<EFBFBD>rer <20> la vol<6F>e les png et pdf
|
|||
|
|
associ<63>s. Pour pouvoir pr<70>ciser des zooms sp<73>cifiques, il faut ajouter
|
|||
|
|
un petit morceau de shell script au Makefile.am :
|
|||
|
|
|
|||
|
|
for figure in DummyFig*.fig; do \
|
|||
|
|
zoom="0.7"; \
|
|||
|
|
case $$figure in \
|
|||
|
|
DummyFig-1.fig) zoom="0.7";; \
|
|||
|
|
DummyFig-2.fig) zoom="0.9";; \
|
|||
|
|
esac; \
|
|||
|
|
fig2dev -L png -m $$zoom $$figure `basename $$figure .fig`.png; \
|
|||
|
|
fig2dev -L pdf -p dummy $$figure `basename $$figure .fig`.pdf; \
|
|||
|
|
done; \
|
|||
|
|
|
|||
|
|
C'est la version la plus complexe, on la simplifiera suivant les
|
|||
|
|
besoins.
|
|||
|
|
|
|||
|
|
|
|||
|
|
4. Modification du ".h"
|
|||
|
|
|
|||
|
|
Pour <20>viter de voir appara<72>tre tous les membres et fonctions membres
|
|||
|
|
il est n<>cessaire de r<>partir membres document<6E>s et membres non document<6E>s
|
|||
|
|
de part et d'autre de la macro "__DOXYGEN_PROCESSOR__".
|
|||
|
|
Identification correcte du namespace : les macros BEGIN_HURRICANE_NAMESPACE
|
|||
|
|
et END_HURRICANE_NAMESPACE emp<6D>che doxygen d'identifier les membres de ce
|
|||
|
|
namespace. Il faut les remplacer par leur version expans<6E>e :
|
|||
|
|
namespace Hurricane {
|
|||
|
|
} // End of Hurricane namespace
|
|||
|
|
Je pense que de toute fa<66>ons, ce n'est pas plus mal pour la clart<72> du code.
|
|||
|
|
|
|||
|
|
Remarque : Si une classe ou une fonction n'est absolument pas document<6E>e
|
|||
|
|
(c.a.d. ni la classe, ni aucun de ses attributs ni aucunes de
|
|||
|
|
ses fonctions membres) elle ne sera pas prise en compte dans
|
|||
|
|
doxygen et il est donc inutile de faire un partage entre
|
|||
|
|
partie document<6E>e ou non.
|
|||
|
|
|
|||
|
|
Exemple, pour la DataBase :
|
|||
|
|
|
|||
|
|
namespace Hurricane {
|
|||
|
|
|
|||
|
|
class DataBase : public DBo {
|
|||
|
|
|
|||
|
|
# if !defined(__DOXYGEN_PROCESSOR__)
|
|||
|
|
|
|||
|
|
// Fonctions & membres non document<6E>s.
|
|||
|
|
// Attributes
|
|||
|
|
private: Technology* _technology;
|
|||
|
|
private: Library* _rootLibrary;
|
|||
|
|
// Constructors
|
|||
|
|
protected: DataBase();
|
|||
|
|
// Others
|
|||
|
|
protected: virtual void _PostCreate();
|
|||
|
|
protected: virtual void _PreDelete();
|
|||
|
|
public: virtual string _GetTypeName() const {return _TName("DataBase");};
|
|||
|
|
public: virtual string _GetString() const;
|
|||
|
|
public: virtual Record* _GetRecord();
|
|||
|
|
public: void _SetTechnology(Technology* technology) {_technology = technology;};
|
|||
|
|
public: void _SetRootLibrary(Library* rootLibrary) {_rootLibrary = rootLibrary;};
|
|||
|
|
public: virtual string _GetHeaderName() const {return "DB";};
|
|||
|
|
public: virtual void _SaveHeaderTo(OutputFile& outputFile);
|
|||
|
|
public: virtual void _SaveContentTo(OutputFile& outputFile);
|
|||
|
|
public: virtual void _Realize(Hurricane::Builder* builder, InputFile& inputFile);
|
|||
|
|
|
|||
|
|
# endif
|
|||
|
|
|
|||
|
|
// Fonctions & membres document<6E>s.
|
|||
|
|
public: static DataBase* Create();
|
|||
|
|
// Accessors
|
|||
|
|
public: Technology* GetTechnology() const {return _technology;};
|
|||
|
|
public: Library* GetRootLibrary() const {return _rootLibrary;};
|
|||
|
|
};
|
|||
|
|
|
|||
|
|
} // End of Hurricane namespace.
|
|||
|
|
|
|||
|
|
|
|||
|
|
5. Ecriture du ".dox"
|
|||
|
|
|
|||
|
|
IMPORTANT : D'un point de vue syntaxique le ".dox" est un fichier C/C++,
|
|||
|
|
il est donc imp<6D>ratif de respecter les r<>gles de syntaxe.
|
|||
|
|
|
|||
|
|
Pour <20>viter d'avoir <20> pr<70>fixer toutes les fonctions/classes par le
|
|||
|
|
namespace Hurricane, il plus <20>l<EFBFBD>gant d'inclure les documentations dans
|
|||
|
|
le namespace lui m<>me.
|
|||
|
|
|
|||
|
|
Indentation : Pour plus de clart<72>, on r<>serve la marge de gauche
|
|||
|
|
pour les mots cl<63>s principaux (\class, \fonction, \section, ...)
|
|||
|
|
Le texte doit commencer sur la 20i<30>me colonne.
|
|||
|
|
|
|||
|
|
Reconnaissance des classes : il n'est plus n<>cessaire d'<27>crire une
|
|||
|
|
classe entre '@' pour qu'elle soit reconnue comme mot cl<63> et transform<72>e
|
|||
|
|
en hyperlien. Par exemple : @DBo@ devient simplement DBo.
|
|||
|
|
Les commandes @remark@ et @caution@ deviennent \remark et \caution.
|
|||
|
|
Les caract<63>res '>' et '<' peuvent <20>tre utilis<69>s directement, au lieu
|
|||
|
|
de > et < .
|
|||
|
|
|
|||
|
|
Classement des fonctions membres par genre : pour cela on utilise
|
|||
|
|
les techniques de "grouping". La structure se compose de trois morceaux :
|
|||
|
|
\name donne le nom du groupe, imm<6D>diatement apr<70>s on ouvre le groupe
|
|||
|
|
avec \{ et on le ferme par \} apr<70>s les fonctions membres du groupe.
|
|||
|
|
|
|||
|
|
/*! \name Constructors & Destructors
|
|||
|
|
*/
|
|||
|
|
// \{
|
|||
|
|
|
|||
|
|
/*! \function DataBase* DataBase::Create ();
|
|||
|
|
* Creates and returns a pointer to a new DataBase.
|
|||
|
|
*
|
|||
|
|
* \caution An exception is thrown if a Database already exists.
|
|||
|
|
*/
|
|||
|
|
|
|||
|
|
// \}
|
|||
|
|
|
|||
|
|
|
|||
|
|
/*! \name Accessors
|
|||
|
|
*/
|
|||
|
|
// \{
|
|||
|
|
|
|||
|
|
/*! \function Technology* DataBase::GetTechnology () const;
|
|||
|
|
* \return the Technology if it exists, else \NULL.
|
|||
|
|
*/
|
|||
|
|
|
|||
|
|
/*! \function Technology* DataBase::GetRootLibrary () const;
|
|||
|
|
* \return the root Library if it exists, else \NULL.
|
|||
|
|
*/
|
|||
|
|
|
|||
|
|
// \}
|
|||
|
|
|
|||
|
|
|
|||
|
|
6. G<>n<EFBFBD>ration de la documentation
|
|||
|
|
|
|||
|
|
|
|||
|
|
Pour <20>viter de recompiler <20> chaque fois Hurricane on peu directement
|
|||
|
|
faire un "make install" dans le r<>pertoire de build :
|
|||
|
|
|
|||
|
|
(cd ~/coriolis/Linux.SLA4x/build/hurricane/documentation/hurricane/doc.new; make install)
|
|||
|
|
|
|||
|
|
NB: Il faut avoir fait tourner huitre au moins une fois avant de pouvoir
|
|||
|
|
utiliser la commande pr<70>c<EFBFBD>dente.
|
|||
|
|
|
|||
|
|
|
|||
|
|
7. Enjoy!
|