neo_doxygen: todo list and known issues

[jcbrinfo]

As requested by @Morriar.

Projet d’importation de la sortie XML de doxygen vers un graphe lu par neo.nit

Référence pour le format de Doxygen: https://github.com/doxygen/doxygen/blob/master/templates/xml/compound.xsd

Progression de l’outil

• [X] Lister les classes.
  • [X] Inclure les relations d’héritage.
  • [ ] Inclure la généricité (moins prioritaire).
• [X] Lister les espaces de noms.
• [X] Lister les fichiers.
• [x] Lister les membres.
  • [ ] Inclure la généricité (moins prioritaire).
• [X] Importer les listes de paramètres.
• [X] Supporter Python.
• [ ] Mettre en forme la documentation (moins prioritaire).

  Glossaire

• Composite (« compound ») : Un répertoire, un fichier ou toute structure habituellement à la racine d’un fichier. Correspond à un fichier XML dans doxygen.
• Genre (« kind ») : Étiquette utilisée pour préciser le méta-type.
• Membre (« member ») : Structure entièrement incluse dans un composite et qui n’est pas un composite.

  Problèmes relevés

  Non-géré par le modèle Nit

• [ ] Général
  • [X] Visibilité « package »
  • [ ] Virtualité
  • [ ] non-virtual
  • [ ] virtual
  • [ ] pure-virtual
  • [X] Absence de projet
  • Tous les groupes à la racine sont lié à un même groupe (portant le nom du projet) et à un même projet.
  • Le nom du projet est spécifié par l’utilisateur.
  • [ ] Tableaux
  • [x] Type constitué d’un nombre indéterminé d’identifiants et de mots-clés
• [ ] Composite
  • [ ] title
  • [ ] Genre
  • [ ] struct
  • [ ] union
  • [ ] protocol
  • [ ] category
  • [ ] exception
  • [ ] singleton
  • [ ] type
  • [X] file
    • Générer un module pour chaque espace de nom utilisé par le fichier.
    • Le nom des modules a la forme suivante : nom_projet::espace_de_nom::nom_fichier.
  • [X] namespace : Utiliser un MGroup.
  • [ ] group
  • [ ] page
  • [ ] example
  • Solutions possibles
    • Ajouter des nouveaux genres.
    • Ajouter un genre style libre (valeur non restreinte).
    • Permetterait de gérer aussi les attributs booléens.
  • [ ] Les attributs booléens abstract, final et sealed
  • Solution possible : mettre dans kind (ce qui est fait pour le moment).
    • Si kind est une énumération, il y a trop de possibilités à considérer.
  • [ ] Visibilité et virtualité de l’héritage
  • Ignoré pour l’instant.
  • [ ] Classes de base à l’extérieur du projet
  • [X] Classes imbriqués
  • [ ] Sections au niveau d’un composite
  • [ ] En-tête
  • [ ] Description
  • [ ] Genre
  • Pour l’instant, l’outil ignore ce niveau et passe directement aux membres.
  • Il est possible que les sections n’aient aucune valeur ajoutée. En fait, ça semble correspondre aux sections que Doxygen génère pour les autres sorties (membres publiques, membres privés, etc.).
• [ ] Membres
  • [ ] Genre
  • [ ] define
  • [ ] event
  • [ ] typedef
  • [ ] enum
  • [ ] signal
  • [ ] property
    • Semble être utilisé pour les propriétés à la Microsoft, c’est-à-dire des triplets let-set-get.
  • [ ] prototype
  • [ ] friend
  • [ ] dcop
  • [ ] slot
  • [ ] service
  • [ ] Virtualité
  • [ ] Redéfinition de la visibilité
  • [ ] Attributs booléens d’un membre
  • [ ] Attribut accessor dans le cas d’un « Objective-C 2.0 property accessor »
  • [ ] Paramètres de « template »
  • [ ] Exceptions levées
  • [ ] Redéfinition de plusieurs membres
  • Doxygen définit la multiplicité de la relation de réimplémentation (équivalent des « redef ») comme étant de 0 à plusieurs dans les deux sens, ce qui cause un problème pour la relation DEFINES (plusieurs vers un).
    • Pour l’instant, je prends la première racine trouvée selon un parcours en largeur.
  • [ ] Plusieurs membres du même nom (surcharge).
  • [x] Membres faisant partie d’un composite qui n’est pas une classe (exemple: directement dans un espace de nom).
• [ ] Paramètre
  • [ ] Valeur par défaut

    Non-géré par Nitdoc

• [ ] Titre au niveau d’un composite : Ignoré pour l’instant.
• [ ] Emplacements
  • [ ] Sans fichier
  • [ ] Sans coordonnées
• [ ] Absence de dépendance explicite entre les modules (exemple: Java)
  • Pour l’instant, Nitdoc utilise l’héritage des classes dans le module pour générer un diagramme, mais ne met aucun lien hypertexte. Aussi, ça donne une vision très limitée du vrai graphe de dépendances.
  • Solution à investiguer : Extraire l’information à partir des diagrammes inclus dans les définitions de composites.
• [ ] Documentation d’un paramètre

  Proplèmes spécifiques à neo.nit

• [ ] La propriété location n’est pas réflexive (le chargeur n’accepte pas tous les formats de Location::to_s).

  Concepts de Doxygen que je ne comprend pas encore complètement

• [ ] Distinctions entre briefdescription, detaileddescription et inbodydescription
  • Pour l’instant, seul detaileddescription est supporté (cas javadoc).
• [ ] title d’un composite.
• [ ] ambiguityscope
• [ ] Les diagrammes (par manque de temps)
  • [ ] Pourrait servir à récupérer les dépendances implicites (à vérifier).
• [x] Le typage (LinkedTextType)
  • Un texte avec zéro, un ou plusieurs liens.
• [ ] L’élément read
• [ ] L’élément write
• [ ] L’élément bitfield
• [ ] L’attribut array : À quoi la valeur correspond-t-elle?

  Ce que Doxygen ne génère pas (ou qui nécessite une configuration)

• [ ] Documentation des espaces de noms
  • Problème possiblement spécifique au vieux code Java, où la documentation n’est pas dans un *.java.
  • Je n’ai pas trouvé d’option pour que Doxygen prenne en compte les package.html.
• [ ] Chemin d’accès relatifs
  • Doxygen semble toujours mettre les chemins absolus pour la sortie XML, peu importe la configuration.
• [ ] Équivalent des attributs is_init, is_intern et is_extern pour les méthodes.
  • Est-ce réellement nécessaire pour Nitdoc?
• [ ] Les liens de redéfinitions sont pas toujours indiqués (pourquoi?).
• [ ] Java: Certains mot-clés ne sont pas interprétés.
  • [X] abstract
  • [X] ...

    Solutions générales proposés

• Pour le manque de flexibilité du modèle.
  • (IMPOSSIBLE) Utiliser des annotations.
  • Les annotations n’interviennent pas au niveau du modèle.
  • (POSSIBLE) Ajouter un dictionnaire de propriétés étendues (sans restrictions) à MEntity.
  • Permet d’apporter rapidement des modifications relatives aux propriétés reconnues.
  • (POSSIBLE) Raffiner les classes du modèle pour ajouter les propriétés dont on a besoin.

[jcbrinfo]

I added an entry about visibility redefinitions.

[jcbrinfo]

It seems that a LinkedText (as the name implies) is simply a text with zero, one or more links. Since this definition do not fit in any MType that are already in the Nit’s model, we may need to add a new subclass of MType to handle Doxygen’s types in Nitdoc. This class would be specific to Nitdoc, so it would only affect neo.nit and nitdoc.

[Morriar]

Hum je suis pas sûr de comprendre le lien entre le modèle (MType) et le contenu d'un commentaire (des liens, LinkedText).

À mon avis, tu essayes de mélanger deux choses qui ne devraient pas l'être.

[jcbrinfo]

In compound.xsd, type elements are defined by LinkedTextType.

See https://github.com/doxygen/doxygen/blob/3b8fea2f1f7f2e6a83a35626e6dec9d114a78c9e/src/compound.xsd#L124

[Morriar]

Encore une fois, ce n'est pas parce que la spec de Doxygen que

1) c'est la bonne chose à faire 2) on doit reproduire l'erreur en Nit. ​ J'aimerais autant éviter de mettre de l'info cosmétique dans le modèle Nit.

[jcbrinfo]

Comment veux-tu que je récupère le type alors?

[privat]

Deux choix:

1. Vous faites une réunion pour vous entende
2. Je décide arbitrairement, sachant que c'est moi qui ait suggéré d'étendre le modèle Nit pour maintenir temprairement de l'information que doxygen a transformé/perdu

[Morriar]

Fais comme Jean t'a dit de faire, c'est lui le chef.

[jcbrinfo]

With #841, we got members! :smiley:

[jcbrinfo]

I get a very weird behavior with redefs: in the same project, Doxygen list them for some members while not linking some other members to their “super” member. The problem seems to affect members with a lot of definitions, that is a method implemented in many subclasses.

[Morriar]

Est-ce que Javadoc suit le même comportement que Doxygen sur ce cas précis?

[jcbrinfo]

Sous Javadoc, tout fonctionne. Il m’indique même pour mes méthodes call : « Specified by: call in class CotFunction. » Ça semble donc un problème du côté de Doxygen.

[jcbrinfo]

Members are typed now! :smiley:

[Morriar]

Good Job!

[jcbrinfo]

Je viens de me rendre compte que Ruby n’est pas supporté officiellement par Doxygen. J’aurais dû vérifier plus tôt… :disappointed:

[Morriar]

Je vais passer te voir ce matin, on va discuter de la suite dans ce cas.

Alexandre

Le 3 novembre 2014 11:18, jcbrinfo notifications@github.com a écrit :

Je viens de me rendre compte que Ruby n’est pas supporté officiellement par Doxygen. J’aurais dû vérifier plus tôt… [image: :disappointed:]

— Reply to this email directly or view it on GitHub https://github.com/privat/nit/issues/837#issuecomment-61502673.

[jcbrinfo]

In Python, inner classes occur a lot (may be more than in Java). So, I my next task is to rewrite FileCompound and ClassCompound to handle them.

[jcbrinfo]

Inner classes are correctly handled now.

[jcbrinfo]

I updated the first message.

[jcbrinfo]

Doxygen now indicates the language: https://github.com/doxygen/doxygen/commit/e986e0039de21791bd1fbb1f59b13f58c4a46324

So, the --src-lang option may disapear in the future…

[jcbrinfo]

Even without test and plat-* stuff, the Python library is too big for nx. It is not surprising considering the problems I got with Apache Xerces…

[jcbrinfo]

@Morriar For reference, <inbodydescription> elements contains all the documentation blocks (that is comments that follow one of the Doxygen’s syntaxes for documentation) found in the body of a member. This is called “in-body descriptions” by the Doxygen’s community. For usage example, see http://stackoverflow.com/a/758211.

In summary, we should not skip these descriptions. In this regard, neo_doxygen currently behaves as expected.

Note: I put this there to avoid the next maintainer to have hard time to figure out the purpose of <inbodydescription>.

Another example (in Java):

/**
 * Brief description (if `JAVADOC_AUTOBRIEF` is set to `YES`).
 *
 * Detailed description.
 */
void f() {
    /* Regular comment.
     * Skipped by Doxygen.
     */
    /** First block of in-body description.
        Notice the doubled asterisk. */
    /*! Second block of in-body description (QT-style). */
}