C++中的注解理解

SAL： the Microsoft Source Code Annotation Language.

　　SAL： the Microsoft Source Code Annotation Language. 　　

　　微软代码注解语言。你可以用sal.h中的宏定义来注释函数的参数和返回值来描述他们的行为。

　　曾经在Java中使用过注解，现在C++中也有注解了。

　　sal.h - markers for documenting the semantics of APIs

　　 sal.h provides a set of annotations to describe how a function uses itsparameters

　　C++中提供了一系列注解，来描述函数怎样来使用他的参数。

---

　　   The macros are defined in 3 layers, plus the structural set:

   _In_/_Out_/_Ret_ Layer:
   ----------------------
   This layer provides the highest abstraction and its macros should be used
   in most cases. These macros typically start with:
      _In_     : input parameter to a function, unmodified by called function
      _Out_    : output parameter, written to by called function, pointed-to
                 location not expected to be initialized prior to call
      _Outptr_ : like _Out_ when returned variable is a pointer type
                 (so param is pointer-to-pointer type). Called function
                 provides/allocated space.
      _Outref_ : like _Outptr_, except param is reference-to-pointer type.
      _Inout_  : inout parameter, read from and potentially modified by
                 called function.
      _Ret_    : for return values
      _Field_  : class/struct field invariants
   For common usage, this class of SAL provides the most concise annotations.
   Note that _In_/_Out_/_Inout_/_Outptr_ annotations are designed to be used
   with a parameter target. Using them with _At_ to specify non-parameter
   targets may yield unexpected results.

   This layer also includes a number of other properties that can be specified
   to extend the ability of code analysis, most notably:
      -- Designating parameters as format strings for printf/scanf/scanf_s
      -- Requesting stricter type checking for C enum parameters

　  上面: 本层提供最高的抽象并且他的宏可应用于大多数场合。他们的宏都以_In_, _Out_ , _Inout开头

 _Pre_/_Post_ Layer:
   ------------------
   The macros of this layer only should be used when there is no suitable macro
   in the _In_/_Out_ layer. Its macros start with _Pre_ or _Post_.
   This layer provides the most flexibility for annotations.

　　上面:当_In_\_Out层没有适当的宏时才被使用，有很强的灵活性，他们的宏都以_Pre_, _Post_, _Ret_,_Deref_pre_ _Deref_post_ , _Deref_ret_开头

　　_Pre_在函数调用前需要知道参数条件的时候

　　_Post_在函数调用后需要知道的参数条件

　　_Ret_ 函数调用后返回的参数条件

　　_Deref_pre_  对于被间接引用的指针数组参数在函数调用前的条件
　　_Deref_post_  对于被间接引用的指针数组参数在函数调用后的条件
　　_Deref_ret

　　_Pre_post在函数调用前或后的条件

　　_Deref_prepost

  Implementation Abstraction Layer:
   --------------------------------
   Macros from this layer should never be used directly. The layer only exists
   to hide the implementation of the annotation macros.

　　上面:本层从不被直接使用，隐藏注释宏的实现

   Structural Layer:
   ----------------
   These annotations, like _At_ and _When_, are used with annotations from
   any of the other layers as modifiers, indicating exactly when and where
   the annotations apply.

　　上面:结构层，明确指定什么时候，在什么地方注解应用。

Common syntactic conventions:  常见的语法约定
   ----------------------------

Usage:
   -----
   _In_, _Out_, _Inout_, _Pre_, _Post_, are for formal parameters（常规参数）.
   _Ret_, _Deref_ret_ must be used for return values.

Nullness:
   --------
   If the parameter can be NULL as a precondition to the function, the
   annotation contains _opt. If the macro does not contain '_opt' the
   parameter cannot be NULL.

If an out/inout parameter returns a null pointer as a postcondition, this is
   indicated by _Ret_maybenull_ or _result_maybenull_. If the macro is not
   of this form, then the result will not be NULL as a postcondition.
     _Outptr_ - output value is not NULL
     _Outptr_result_maybenull_ - output value might be NULL

String Type:
   -----------
   _z: NullTerminated string
   for _In_ parameters the buffer must have the specified stringtype before the call
   for _Out_ parameters the buffer must have the specified stringtype after the call
   for _Inout_ parameters both conditions apply

Extent Syntax:
   -------------
   Buffer sizes are expressed as element counts, unless the macro explicitly
   contains _byte_ or _bytes_. Some annotations specify two buffer sizes, in
   which case the second is used to indicate how much of the buffer is valid
   as a postcondition. This table outlines the precondition buffer allocation
   size, precondition number of valid elements, postcondition allocation size,
   and postcondition number of valid elements for representative buffer size
 aaarticlea/png;base64,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" alt="" />

For the _Outptr_ annotations, the buffer in question is at one level of
   dereference. The called function is responsible for supplying the buffer.

Success and failure:
   -------------------
   The SAL concept of success allows functions to define expressions that can
   be tested by the caller, which if it evaluates to non-zero, indicates the
   function succeeded, which means that its postconditions are guaranteed to
   hold.  Otherwise, if the expression evaluates to zero, the function is
   considered to have failed, and the postconditions are not guaranteed.

The success criteria can be specified with the _Success_(expr) annotation:
     _Success_(return != FALSE) BOOL
     PathCanonicalizeA(_Out_writes_(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath) :
        pszBuf is only guaranteed to be NULL-terminated when TRUE is returned,
        and FALSE indiates failure. In common practice, callers check for zero
        vs. non-zero returns, so it is preferable to express the success
        criteria in terms of zero/non-zero, not checked for exactly TRUE.

Functions can specify that some postconditions will still hold, even when
   the function fails, using _On_failure_(anno-list), or postconditions that
   hold regardless of success or failure using _Always_(anno-list).

The annotation _Return_type_success_(expr) may be used with a typedef to
   give a default _Success_ criteria to all functions returning that type.
   This is the case for common Windows API status types, including
   HRESULT and NTSTATUS.  This may be overridden on a per-function basis by
   specifying a _Success_ annotation locally.