In quale sintassi dovrebbe essere scritto un documento di riferimento SDK COM? [chiuso]

Question

Ho un SDK COM scritto in C ++ e vorrei creare la documentazione per il mio prodotto. Capisco che la maggior parte delle persone probabilmente non utilizzerà C ++ per l'integrazione con questo componente COM, ma molti lo faranno.

Quale metodo è meglio descrivere l'API, senza perdere i dettagli che uno sviluppatore C ++ dovrebbe conoscere.

Answer 1

Puoi scrivere la documentazione direttamente nell'IDL usando gli attributi helpstring - la maggior parte dei consumatori del tuo codice sarà in grado di leggerlo direttamente usando, ad esempio, OLE View o nel proprio browser degli oggetti. La nostra azienda ha scritto uno strumento interno per estrarre la documentazione del supporto tecnico e trasformarla in documentazione di riferimento interna in HTML.

Inoltre, puoi utilizzare uno strumento come doxygen per documentare le interfacce: genererà HTML, PDF , Documentazione in formato LaTeX ecc.

Answer 2

IDL è sicuramente una buona idea per un riferimento. Ma suppongo che vorrai fornire esempi di codice e frammenti.

Ecco alcuni pensieri:

• Che tipo di interfaccia COM espone? IDispatch, personalizzato, doppio? Probabilmente hai preso questa decisione indovinando chi è il tuo pubblico SDK, quindi quale lingua usano.

• Dovresti usare solo una lingua? Forse puoi fornire alcuni esempi in C ++, alcuni in VB6, altri in .NET (VB o C #).

• Scegli la lingua per un dato esempio in base alla difficoltà (o alla sua mancanza) di utilizzare il tipo specifico di argomenti in quella lingua.