Qual é o propósito de __in __out __in_opt __allowed(), como eles funcionam?Devo usar construções semelhantes em meu próprio código?
Pergunta
Algumas dessas definições de pré-processador estão na função WinMain e em outras funções da biblioteca do Windows.Qual é o seu propósito?Como eles funcionam?e é uma boa prática escrevê-los em suas implementações ou chamadas de função?
Minha pesquisa inicial sugere que eles são simplesmente configurados de forma equivalente a:
#define __in
#define __out
#define __in_opt
O que significa que eles são substituídos por nada na passagem do pré-processador.São apenas um método de documentação, sem nenhuma funcionalidade?
Nesse caso, posso ver a vantagem de documentar o código em linha como esta.Com algo como doxygen você precisa escrever os nomes dos parâmetros duas vezes.Então, isso poderia, em teoria, ajudar a reduzir a duplicação e manter a consistência...
Não tenho teoria sobre como __allowed()
deveria funcionar.
Solução
São anotações SAL na linguagem de anotação do código-fonte. A Microsoft Tooling depende disso. O artigo da biblioteca MSDN é aqui. Um bom exemplo é Análise de código. Outra ferramenta bastante não relacionada, mas capacitada por essas anotações é o Assistente de Interopa de Pinvoke.
Outras dicas
As anotações SAL são úteis para duas coisas:
- Análise estática através do pré -rápido (compilar com /analisar)
- Os leitores humanos podem analisar as anotações e descobrir como uma função deve ser chamada e determinar rapidamente os parâmetros de entrada/saída.
As macros de fato se expandem para várias expressões de DeclSpec quando seu código é compilado com a análise. Eu uso essas anotações o tempo todo no meu código.
Eles são usados em uma ferramenta de análise semântica da Microsoft como marcações de código.A menos que você planeje usar essa ferramenta sozinho, não há muito propósito em usá-la.
Essas macros da Microsoft geralmente se expandem para nada e são feitas como dicas para o leitor.
No entanto, da última vez que verifiquei, por exemplo, o sugestão do MessageBox
Os argumentos estavam completamente errados, sugerindo que o primeiro, o segundo e o terceiro argumento tinham padrões úteis (quando você especifica 0), enquanto, na realidade, é o primeiro e o quarto argumento que têm padrões úteis. Talvez também o argumento do título que padroniza para "erro", mas nunca achei isso útil. Portanto, é apenas uma coisa da Microsoft, sugere que você não pode e não deve confiar, apenas enganando a desordem visual.
Cheers & hth.,