fixes #1048

Author: mikeblome

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

@@ -1,6 +1,6 @@
 ---
 title: Annotating Structs and Classes
-ms.date: 11/04/2016
+ms.date: 06/28/2019
 ms.topic: "conceptual"
 f1_keywords:
   - "_Field_size_bytes_part_"
@@ -26,6 +26,7 @@ ms.workload:
   - "multiple"
 ---
 # Annotating Structs and Classes
+
 You can annotate struct and class members by using annotations that act like invariants—they are presumed to be true at any function call or function entry/exit that involves the enclosing structure as a parameter or a result value.
 
 ## Struct and Class Annotations
@@ -70,6 +71,39 @@ You can annotate struct and class members by using annotations that act like inv
     min(pM->nSize, sizeof(MyStruct))
     ```
 
+## Example
+
+```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 MyBuffer
+{
+    static int MaxBufferSize;
+    
+    _Field_z_
+    const char* name;
+    
+    int firstField;
+
+    // ... other fields
+
+    _Field_range_(1, MaxBufferSize)
+    int bufferSize;
+    _Field_size_(bufferSize)        // Prefered way - easier to read and maintain.
+    int buffer[0];
+};
+```
+
+Notes for this example:
+
+- `_Field_z_` is equivalent to `_Null_terminated_`.  `_Field_z_` for the name field specifies that the name field is a null-terminated string.
+- `_Field_range_` for `bufferSize` specifies that the value of `bufferSize` should be within 1 and `MaxBufferSize` (both inclusive).
+- The end results of the `_Struct_size_bytes_` and `_Field_size_` annotations are equivalent. For structures or classes that have a similar layout, `_Field_size_` is easier to read and maintain, because it has fewer references and calculations than the equivalent `_Struct_size_bytes_` annotation. `_Field_size_` doesn’t require conversion to the byte size. If byte size is the only option, for example, for a void pointer field, `_Field_size_bytes_` can be used. If both `_Struct_size_bytes_` and `_Field_size_` exist, both will be available to tools. It is up to the tool what to do if the two annotations disagree.
+
 ## See Also
 
 - [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md)