Merge pull request #4429 from Rastaban/update_examples

enable syntax highlighting in C/C++ examples

Author: American-Dipper

docs/code-quality/annotating-function-parameters-and-return-values.md

@@ -179,7 +179,10 @@ For the annotations in the following table, when a pointer parameter is being an
 
      A pointer to an array of `s` elements (resp. bytes) that will be written by the function.  The array elements do not have to be valid in pre-state, and the number of elements that are valid in post-state is unspecified.  If there are annotations on the parameter type, they are applied in post-state. For example, consider the following code.
 
-     `typedef _Null_terminated_ wchar_t *PWSTR; void MyStringCopy(_Out_writes_ (size) PWSTR p1,    _In_ size_t size,    _In_ PWSTR p2);`
+     ```cpp
+     typedef _Null_terminated_ wchar_t *PWSTR;
+     void MyStringCopy(_Out_writes_(size) PWSTR p1, _In_ size_t size, _In_ PWSTR p2);
+     ```
 
      In this example, the caller provides a buffer of `size` elements for `p1`.  `MyStringCopy` makes some of those elements valid. More importantly, the `_Null_terminated_` annotation on `PWSTR` means that `p1` is null-terminated in post-state.  In this way, the number of valid elements is still well-defined, but a specific element count is not required.
 
@@ -209,13 +212,14 @@ For the annotations in the following table, when a pointer parameter is being an
 
      `_Out_writes_bytes_all_(s)`
 
-     A pointer to an array of `s` elements.  The elements do not have to be valid in pre-state.  In post-state, the elements up to the `c`-th element must be valid.  If the size is known in bytes, scale `s` and `c` by the element size or use the `_bytes_` variant, which is defined as:
+     A pointer to an array of `s` elements.  The elements do not have to be valid in pre-state.  In post-state, the elements up to the `c`-th element must be valid.  The `_bytes_` variant can be used if the size is known in bytes rather than number of elements.
+     
+     For example:
 
-     `_Out_writes_to_(_Old_(s), _Old_(s))    _Out_writes_bytes_to_(_Old_(s), _Old_(s))`
-
-     In other words, every element that exists in the buffer up to `s` in the pre-state is valid in the post-state.  For example:
-
-     `void *memcpy(_Out_writes_bytes_all_(s) char *p1,    _In_reads_bytes_(s) char *p2,    _In_ int s); void * wordcpy(_Out_writes_all_(s) DWORD *p1,     _In_reads_(s) DWORD *p2,    _In_ int s);`
+     ```cpp
+     void *memcpy(_Out_writes_bytes_all_(s) char *p1, _In_reads_bytes_(s) char *p2, _In_ int s); 
+     void *wordcpy(_Out_writes_all_(s) DWORD *p1, _In_reads_(s) DWORD *p2, _In_ int s);
+     ```
 
 - `_Inout_updates_to_(s,c)`
 
@@ -239,19 +243,24 @@ For the annotations in the following table, when a pointer parameter is being an
 
 - `_In_reads_to_ptr_(p)`
 
-     A pointer to an array for which the expression `p` - `_Curr_` (that is, `p` minus `_Curr_`) is defined by the appropriate language standard.  The elements prior to `p` must be valid in pre-state.
+     A pointer to an array for which `p - _Curr_` (that is, `p` minus `_Curr_`) is a valid expression.  The elements prior to `p` must be valid in pre-state.
+
+    For Example:
+    ```cpp
+    int ReadAllElements(_In_reads_to_ptr_(EndOfArray) const int *Array, const int *EndOfArray);
+    ```
 
 - `_In_reads_to_ptr_z_(p)`
 
-     A pointer to a null-terminated array for which the expression `p` - `_Curr_` (that is, `p` minus `_Curr_`) is defined by the appropriate language standard.  The elements prior to `p` must be valid in pre-state.
+     A pointer to a null-terminated array for which expression `p - _Curr_` (that is, `p` minus `_Curr_`) is a valid expression.  The elements prior to `p` must be valid in pre-state.
 
 - `_Out_writes_to_ptr_(p)`
 
-     A pointer to an array for which the expression `p` - `_Curr_` (that is, `p` minus `_Curr_`) is defined by the appropriate language standard.  The elements prior to `p` do not have to be valid in pre-state and must be valid in post-state.
+     A pointer to an array for which `p - _Curr_` (that is, `p` minus `_Curr_`) is a valid expression.  The elements prior to `p` do not have to be valid in pre-state and must be valid in post-state.
 
 - `_Out_writes_to_ptr_z_(p)`
 
-     A pointer to a null-terminated array for which the expression `p` - `_Curr_` (that is, `p` minus `_Curr_`) is defined by the appropriate language standard.  The elements prior to `p` do not have to be valid in pre-state and must be valid in post-state.
+     A pointer to a null-terminated array for which `p - _Curr_` (that is, `p` minus `_Curr_`) is a valid expression.  The elements prior to `p` do not have to be valid in pre-state and must be valid in post-state.
 
 ## Optional Pointer Parameters
 
@@ -355,7 +364,7 @@ Output pointer parameters require special notation to disambiguate null-ness on
 
 ## Output Reference Parameters
 
-A common use of the reference parameter is for output parameters.  For simple output reference parameters—for example, `int&`—`_Out_` provides the correct semantics.  However, when the output value is a pointer—for example `int *&`—the equivalent pointer annotations like `_Outptr_ int **` don't provide the correct semantics.  To concisely express the semantics of output reference parameters for pointer types, use these composite annotations:
+A common use of the reference parameter is for output parameters.  For simple output reference parameters such as `int&`, `_Out_` provides the correct semantics.  However, when the output value is a pointer such as `int *&`, the equivalent pointer annotations like `_Outptr_ int **` don't provide the correct semantics.  To concisely express the semantics of output reference parameters for pointer types, use these composite annotations:
 
 **Annotations and Descriptions**
 

docs/code-quality/annotating-locking-behavior.md

@@ -67,7 +67,7 @@ The following table lists the locking annotations.
 |`_Create_lock_level_(name)`|A statement that declares the symbol `name` to be a lock level so that it may be used in the annotations `_Has_Lock_level_` and `_Lock_level_order_`.|
 |`_Has_lock_kind_(kind)`|Annotates any object to refine the type information of a resource object. Sometimes a common type is used for different kinds of resources and the overloaded type is not sufficient to distinguish the semantic requirements among various resources. Here's a list of pre-defined `kind` parameters:<br /><br /> `_Lock_kind_mutex_`<br /> Lock kind ID for mutexes.<br /><br /> `_Lock_kind_event_`<br /> Lock kind ID for events.<br /><br /> `_Lock_kind_semaphore_`<br /> Lock kind ID for semaphores.<br /><br /> `_Lock_kind_spin_lock_`<br /> Lock kind ID for spin locks.<br /><br /> `_Lock_kind_critical_section_`<br /> Lock kind ID for critical sections.|
 |`_Has_lock_level_(name)`|Annotates a lock object and gives it the lock level of `name`.|
-|`_Lock_level_order_(name1, name2)`|A statement that gives the lock ordering between `name1` and `name2`.|
+|`_Lock_level_order_(name1, name2)`|A statement that gives the lock ordering between `name1` and `name2`.  Locks that have level `name1` must be acquired before locks that have level `name2`|
 |`_Post_same_lock_(expr1, expr2)`|Annotates a function and indicates that in post state the two locks, `expr1` and `expr2`, are treated as if they are the same lock object.|
 |`_Releases_exclusive_lock_(expr)`|Annotates a function and indicates that in post state the function decrements by one the exclusive lock count of the lock object that's named by `expr`.|
 |`_Releases_lock_(expr)`|Annotates a function and indicates that in post state the function decrements by one the lock count of the lock object that's named by `expr`.|

docs/code-quality/annotating-structs-and-classes.md

@@ -75,11 +75,9 @@ You can annotate struct and class members by using annotations that act like inv
 
 ```cpp
 #include <sal.h>
-// For FIELD_OFFSET macro
-#include <windows.h>
 
 // This _Struct_size_bytes_ is equivalent to what below _Field_size_ means.
-_Struct_size_bytes_(FIELD_OFFSET(MyBuffer, buffer) + bufferSize * sizeof(int))
+_Struct_size_bytes_(__builtin_offsetof(MyBuffer, buffer) + bufferSize * sizeof(int))
 struct MyBuffer
 {
     static int MaxBufferSize;
@@ -93,8 +91,9 @@ struct MyBuffer
 
     _Field_range_(1, MaxBufferSize)
     int bufferSize;
+    
     _Field_size_(bufferSize)        // Prefered way - easier to read and maintain.
-    int buffer[0];
+    int buffer[]; // Using C99 Flexible array member
 };
 ```
 

docs/code-quality/c26100.md

@@ -21,7 +21,7 @@ warning C26100: Race condition. Variable \<var> should be protected by lock \<lo
 ## Example
  The following example generates warning C26100 because there is a violation of the `_Guarded_by_` contract.
 
-```
+```cpp
 CRITICAL_SECTION gCS;
 
 _Guarded_by_(gCS) int gData;
@@ -52,8 +52,7 @@ void Unsafe(DATA* p) {
 ## Example
  Occasionally a shared variable only has to be guarded for write access but not for read access. In that case, use the `_Write_guarded_by_` annotation, as shown in the following example.
 
-```
-
+```cpp
 CRITICAL_SECTION gCS;
 
 _Guarded_by_(gCS) int gData;

docs/code-quality/c26101.md

@@ -21,8 +21,7 @@ warning C26101: Failing to use interlocked operation properly for variable \<var
 ## Example
  The following example generates warning C26101 because there is a violation of the `_Interlocked_` contract.
 
-```
-
+```cpp
 CRITICAL_SECTION cs;
 typedef struct _DATA
 {

docs/code-quality/c26105.md

@@ -21,8 +21,7 @@ warning C26105: Lock order violation. Acquiring lock \<lock> with level \<level>
 ## Example
  The following example generates warning C26105 because there is a lock order inversion in the function `OrderInversion`.
 
-```
-
+```cpp
 _Create_lock_level_(MutexLockLevel);
 _Create_lock_level_(TunnelLockLevel);
 _Create_lock_level_(ChannelLockLevel);

docs/code-quality/c26110.md

@@ -21,8 +21,7 @@ warning C26110: Caller failing to hold lock \<lock> before calling function \<fu
 ## Example
  In the following example, warning C26110 is generated because the annotation `_Requires_lock_held_` on function `LockRequired` states that the caller of `LockRequired` must acquire the lock before it calls `LockRequired`. Without this annotation, `LockRequired` has to acquire the lock before it accesses any shared data protected by the lock.
 
-```
-
+```cpp
 typedef struct _DATA
 {
     CRITICAL_SECTION cs;

docs/code-quality/c26111.md

@@ -21,8 +21,7 @@ warning C26111: Caller failing to release lock \<lock> before calling function \
 ## Example
  The following example generates warning C26111 because the `_Requires_lock_not_held_` precondition is violated by the call to `DoNotLock` within the locked section.
 
-```
-
+```cpp
 typedef struct _DATA
 {
     CRITICAL_SECTION cs;

docs/code-quality/c26112.md

@@ -21,8 +21,7 @@ warning C26112: Caller cannot hold any lock before calling \<func>.
 ## Example
  The following example generates warning C26112 because the `_Requires_no_locks_held_` precondition is violated by the call to `NoLocksAllowed` within the locked section.
 
-```
-
+```cpp
 typedef struct _DATA
 {
     CRITICAL_SECTION cs;

docs/code-quality/c26115.md

@@ -23,8 +23,7 @@ warning C26115: Failing to release lock \<lock> in function \<func>.
 ## Example
  The following example generates warning C26115 because there is an orphaned lock in a function that is not annotated with `_Acquires_lock_`.
 
-```
-
+```cpp
 typedef struct _DATA
 {
     CRITICAL_SECTION cs;

docs/code-quality/c26116.md

@@ -21,8 +21,7 @@ warning C26116: Failing to acquire or to hold lock \<lock> in \<func>.
 ## Example
  The following example generates warning C26116 because the function `DoesNotLock` was annotated with `_Acquires_lock_` but does not acquire it. The function `DoesNotHoldLock` generates the warning because it is annotated with `_Requires_lock_held` and does not hold it.
 
-```
-
+```cpp
 typedef struct _DATA
 {
     CRITICAL_SECTION cs;

docs/code-quality/c26130.md

@@ -21,8 +21,7 @@ warning C26130: Missing annotation \_Requires\_lock\_held\_(\<lock>) or \_No\_co
 ## Example
  In the following example, warning C26130 is generated because a `_Guarded_by_` member is being modified without a lock.
 
-```
-
+```cpp
 typedef struct _DATA
 {
     CRITICAL_SECTION cs;
@@ -38,8 +37,7 @@ void Init(DATA* p)
 ## Example
  If the previous code is guaranteed to be operated in a single threaded mode, annotate the function by using `_No_competing_thread_`, as shown in the following example.
 
-```
-
+```cpp
 typedef struct _DATA
 {
     CRITICAL_SECTION cs;
@@ -55,8 +53,7 @@ _No_competing_thread_ void Init(DATA* p)
 ## Example
  Alternatively, you can annotate a code fragment by using `_No_competing_thread_begin_` and `_No_competing_thread_end_`, as follows.
 
-```
-
+```cpp
 typedef struct _DATA
 {
     CRITICAL_SECTION cs;

docs/code-quality/c26135.md

@@ -21,8 +21,7 @@ warning C26135: Missing annotation \<annotation> at function \<func>.
 ## Example
  The following example generates warning C26135 because an appropriate side effect annotation is missing.
 
-```
-
+```cpp
 typedef struct _DATA
 {
     CRITICAL_SECTION cs;
@@ -46,8 +45,7 @@ void MyLeave(DATA* p)
 ## Example
  Warning C26135 is also issued when a conditional locking side effect is detected. To annotate a conditional effect, use the `_When_(ConditionExpr, LockAnnotation)` annotation, where `LockAnnotation` is either `_Acquires_lock_` or `_Releases_lock_` and the predicate expression `ConditionExpr` is a Boolean conditional expression. The side effects of other annotations on the same function only occur when `ConditionExpr` evaluates to true. Because `ConditionExpr` is used to relay the condition back to the caller, it must involve variables that are recognized in the calling context. These include function parameters, global or class member variables, or the return value. To see the return value, use a special keyword in the annotation, `return`, as shown in the following example.
 
-```
-
+```cpp
  typedef struct _DATA
  {
      CRITICAL_SECTION cs;

docs/code-quality/c26140.md

@@ -18,8 +18,7 @@ warning C26140: Undefined lock kind \<lock> in annotation \<annotation> on lock
 
 ## Example
 
-```
-
+```cpp
 _Has_lock_kind_(MUTEXa) HANDLE gMutex;
 
 struct CorrectExample

docs/code-quality/c28103.md

@@ -21,13 +21,13 @@ warning C28103: Leaking resource
 ## Example
  The following code example generates this warning:
 
-```
+```cpp
 res = KeSaveFloatingPointState(buffer);
 ```
 
  The following code example avoids this warning:
 
-```
+```cpp
 res = KeSaveFloatingPointState(buffer);
 if (NT_SUCCESS(res))
 {

docs/code-quality/c28104.md

@@ -22,7 +22,7 @@ warning C28104: Resource that should have been acquired before function exit was
 
 ## Example
 
-```
+```cpp
 __drv_acquireResourceGlobal(HWLock, lockid)
 void GetHardwareLock(lockid)
 #pragma warning (suppress: 28104)

docs/code-quality/c28105.md

@@ -21,7 +21,7 @@ Warning C28105: Leaking resource due to an exception
 ## Example
  The following code example generates this warning:
 
-```
+```cpp
 res = KeSaveFloatingPointState(buffer);
 
 res = AllocateResource(Resource);
@@ -33,7 +33,7 @@ FreeResource(Resource)
 
  The following code example avoids this warning:
 
-```
+```cpp
 res = AllocateResource(Resource);
 char *p2;
 

docs/code-quality/c28106.md

@@ -21,16 +21,16 @@ Warning C28106: Variable already holds resource possibly causing leak
 ## Example
  The following code example generates this warning:
 
-```
+```cpp
 ExAcquireResourceLite(resource, true);
-...
+//...
 ExAcquireResourceLite(resource, true);
 ```
 
  The following code example avoids this warning:
 
-```
+```cpp
 ExAcquireResourceLite(resource1, true);
-...
+//...
 ExAcquireResourceLite(resource2, true);
 ```

docs/code-quality/c28107.md

@@ -21,14 +21,14 @@ warning C28107: Resource must be held when calling function
 ## Example
  The following code example generates this warning:
 
-```
+```cpp
 ExAcquireResourceLite(resource, true);
 ExReleaseResourceLite(resource);
 ```
 
  The following code example avoids this warning:
 
-```
+```cpp
 KeEnterCriticalRegion();
 ExAcquireResourceLite(resource, true);
 ExReleaseResourceLite(resource);

docs/code-quality/c28108.md

@@ -21,16 +21,16 @@ warning C28108: Variable holds an unexpected resource
 ## Example
  The following code example generates this warning:
 
-```
+```cpp
 KeAcquireInStackSpinLock(spinLock, lockHandle);
-...
+//...
 KeReleaseSpinLock(spinLock, 0);
 ```
 
  The following code example avoids this warning:
 
-```
+```cpp
 KeAcquireInStackSpinLock(spinLock, lockHandle);
-...
+//...
 KeReleaseInStackSpinLock(lockHandle);
 ```

docs/code-quality/c28109.md

@@ -21,14 +21,14 @@ warning C28109: Variable cannot be held at the time function is called
 ## Example
  The following code example generates this warning:
 
-```
+```cpp
 ExAcquireResourceLite(resource, true);
-...
+//...
 ExAcquireResourceLite(resource, true);
 ```
 
  The following code example avoids this warning:
 
-```
+```cpp
 ExAcquireResourceLite(resource, true);
 ```

docs/code-quality/c28113.md

@@ -23,12 +23,12 @@ warning C28113: Accessing a local variable via an Interlocked function
 ## Example
  Typically, the return value of an Interlocked executive support routine is used in subsequent computations, instead of the input arguments. Also, the Interlocked routines only protect the first (leftmost) argument. Using an Interlocked routine in the following way does not protect the value of global and often serves no purpose.
 
-```
+```cpp
 InterlockedExchange(&local, global)
 ```
 
  The following form has the same effect on the data and safely accesses the global variable.
 
-```
+```cpp
 local = InterllockedExchange(&global, global)
 ```