What is the purpose of __in __out __in_opt __allowed(), how do they work? Should I use similar constructs in my own code?

Question

Some of these Preprocessor definitions are in the WinMain function and other windows library functions. What is their purpose? How do they work? and is it good practice to write them into your implementations or function calls?

My initial research suggests they're simply set up equlivalent to:

#define __in 
#define __out
#define __in_opt

Meaning they get replaced with nothing on the Preprocessor pass. Are they just a documentation method, without any functionality?

If so, I can see the advantage to documenting the code in line like this. With something like doxygen you need to write out the parameter names twice. So this could in theory help reduce duplication, and maintain consistency...

I have no theory for how __allowed() is supposed to work.

Answer 1

They are SAL annotations in the Source-code Annotation Language. Microsoft tooling depends on it. The MSDN Library article is here. A good example is Code Analysis. Another quite unrelated tool, but empowered by these annotations is the Pinvoke Interop Assistant.

Answer 2

SAL annotations are useful for two things:

• Static analysis through PREfast (compile with /analyze)
• Human readers can look at the annotations and figure out how a function should be called, and quickly determine the input/output parameters.

The macros do in fact expand to various declspec expressions when your code is compiled with analysis on. I use these annotations all the time in my code.

Answer 3

They're used in a Microsoft semantic analysis tool as code markups. Unless you plan on using this tool yourself, there's little purpose in using them.