What is the purpose of __in __out __in_opt __allowed(), how do they work? Should I use similar constructs in my own code?
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
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.