J'ai un SDK COM écrit en C++ et j'aimerais créer de la documentation pour mon produit. Je comprends que la plupart des gens n'utiliseront probablement pas C++ pour l'intégration avec ce composant COM, mais beaucoup le feront.Dans quelle syntaxe doit-on écrire un document de référence COM SDK?
Quelle méthode est la meilleure pour décrire l'API, sans perdre les détails qu'un développeur C++ aurait besoin de connaître.
Vous pouvez écrire la documentation directement dans l'IDL en utilisant les attributs helpstring - la plupart des utilisateurs de votre code pourront le lire directement en utilisant, par exemple, OLE View ou dans leur navigateur d'objets. Notre société a écrit un outil interne pour extraire la documentation de l'aide et la transformer en documentation de référence interne en HTML.
De plus, vous pouvez utiliser un outil tel que doxygen pour documenter les interfaces - il produira une documentation au format HTML, PDF, LaTeX etc.
IDL est certainement une bonne idée pour une référence. Mais je suppose que vous voudrez fournir des exemples de code et des extraits.
Voici quelques réflexions:
Quel type d'interface COM Expose-? IDispatch, personnalisé, double? Vous avez probablement pris cette décision en devinant qui est votre public SDK, d'où le langage qu'ils utilisent.
Si vous utilisez une seule langue? Peut-être que vous pouvez fournir quelques exemples en C++, certains en VB6, certains en .NET (VB ou C#).
Choisissez la langue d'un exemple donné en fonction de la difficulté (ou de son manque) d'utilisation du type spécifique d'arguments dans cette langue.
Qu'avez-vous fini par utiliser? Je n'ai pas encore trouvé quelque chose qui gère bien les propriétés - ils sont tous documentés comme des fonctions précédées de get_ou de set_prenant des arguments. –