Em que sintaxe deve um documento de referência COM SDK ser escrito? [fechadas]

Question

Eu tenho um SDK COM escrito em C ++ e eu gostaria de criar documentação para o meu produto. Eu entendo que a maioria das pessoas provavelmente não vai usar C ++ para a integração com este componente COM, mas muitos vontade.

Qual é o melhor método para descrever a API, sem perder detalhes que um desenvolvedor C ++ precisa saber.

Answer 1

Você pode escrever a documentação diretamente no IDL usando os atributos helpstring - a maioria dos consumidores de seu código será capaz de ler isso diretamente usando, por exemplo, Vista OLE ou no seu navegador objeto. Nossa empresa escreveu uma ferramenta interna para extrair a documentação helpstring e transformá-lo em documentação de referência interna em HTML.

Além disso, você pode usar uma ferramenta como doxygen para documentar as interfaces - que irá saída HTML, PDF , LaTeX etc. documentação formato.

Answer 2

IDL é certamente uma boa ideia para uma referência. Mas eu acho que você vai querer fornecer exemplos de código e trechos.

Aqui estão alguns pensamentos:

• Que tipo de COM interface de ele expor? IDispatch, costume, dual? Você provavelmente tomou essa decisão por adivinhar quem é seu público SDK é, portanto, o que a linguagem que eles usam.

• Você deve usar apenas um idioma? Talvez você possa dar alguns exemplos em C ++, alguns em VB6, alguns em .NET (ou VB ou C #).

• Escolha o idioma para um exemplo dado baseado na dificuldade (ou falta dela) para utilizar o tipo específico de argumentos nesse idioma.