Skip to content

Commit 1b0f246

Browse files
authored
Merge pull request #1195 from msebolt/windows-formatting-review-pr15
windows formatting review pr15
2 parents d72c7f6 + 1be99fb commit 1b0f246

30 files changed

Lines changed: 793 additions & 832 deletions

‎docs/windows/out-cpp.md‎

Lines changed: 47 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,47 @@
1-
---
2-
title: "out (C++) | Microsoft Docs"
3-
ms.custom: ""
4-
ms.date: "11/04/2016"
5-
ms.technology: ["cpp-windows"]
6-
ms.topic: "reference"
7-
f1_keywords: ["vc-attr.out"]
8-
dev_langs: ["C++"]
9-
helpviewer_keywords: ["out attribute"]
10-
ms.assetid: 5051b1bf-4949-4bf1-b82f-35e14f0f244b
11-
author: "mikeblome"
12-
ms.author: "mblome"
13-
ms.workload: ["cplusplus", "uwp"]
14-
---
15-
# out (C++)
16-
Identifies pointer parameters that are returned from the called procedure to the calling procedure (from the server to the client).
17-
18-
## Syntax
19-
20-
```
21-
22-
[out]
23-
24-
```
25-
26-
## Remarks
27-
The **out** C++ attribute has the same functionality as the [out](http://msdn.microsoft.com/library/windows/desktop/aa367136) MIDL attribute.
28-
29-
## Example
30-
See the example for [bindable](../windows/bindable.md) for a sample use of **out**.
31-
32-
## Requirements
33-
34-
### Attribute Context
35-
36-
|||
37-
|-|-|
38-
|**Applies to**|Interface parameter|
39-
|**Repeatable**|No|
40-
|**Required attributes**|None|
41-
|**Invalid attributes**|None|
42-
43-
For more information about the attribute contexts, see [Attribute Contexts](../windows/attribute-contexts.md).
44-
45-
## See Also
46-
[IDL Attributes](../windows/idl-attributes.md)
47-
[Parameter Attributes](../windows/parameter-attributes.md)
48-
[defaultvalue](../windows/defaultvalue.md)
49-
[id](../windows/id.md)
1+
---
2+
title: "out (C++) | Microsoft Docs"
3+
ms.custom: ""
4+
ms.date: "11/04/2016"
5+
ms.technology: ["cpp-windows"]
6+
ms.topic: "reference"
7+
f1_keywords: ["vc-attr.out"]
8+
dev_langs: ["C++"]
9+
helpviewer_keywords: ["out attribute"]
10+
ms.assetid: 5051b1bf-4949-4bf1-b82f-35e14f0f244b
11+
author: "mikeblome"
12+
ms.author: "mblome"
13+
ms.workload: ["cplusplus", "uwp"]
14+
---
15+
# out (C++)
16+
Identifies pointer parameters that are returned from the called procedure to the calling procedure (from the server to the client).
17+
18+
## Syntax
19+
20+
```
21+
[out]
22+
```
23+
24+
## Remarks
25+
The **out** C++ attribute has the same functionality as the [out](http://msdn.microsoft.com/library/windows/desktop/aa367136) MIDL attribute.
26+
27+
## Example
28+
See the example for [bindable](../windows/bindable.md) for a sample use of **out**.
29+
30+
## Requirements
31+
32+
### Attribute Context
33+
34+
|||
35+
|-|-|
36+
|**Applies to**|Interface parameter|
37+
|**Repeatable**|No|
38+
|**Required attributes**|None|
39+
|**Invalid attributes**|None|
40+
41+
For more information about the attribute contexts, see [Attribute Contexts](../windows/attribute-contexts.md).
42+
43+
## See Also
44+
[IDL Attributes](../windows/idl-attributes.md)
45+
[Parameter Attributes](../windows/parameter-attributes.md)
46+
[defaultvalue](../windows/defaultvalue.md)
47+
[id](../windows/id.md)

‎docs/windows/override-cpp-component-extensions.md‎

Lines changed: 17 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -12,21 +12,20 @@ ms.author: "mblome"
1212
ms.workload: ["cplusplus", "uwp"]
1313
---
1414
# override (C++ Component Extensions)
15-
The `override` context-sensitive keyword indicates that a member of a type overrides a base class or a base interface member.
15+
The **override** context-sensitive keyword indicates that a member of a type overrides a base class or a base interface member.
1616

1717
## Remarks
18-
The `override` keyword is valid when compiling for native targets (default compiler option), Windows Runtime targets (**/ZW** compiler option), or common language runtime targets (**/clr** compiler option).
18+
The **override** keyword is valid when compiling for native targets (default compiler option), Windows Runtime targets (`/ZW` compiler option), or common language runtime targets (`/clr` compiler option).
1919

2020
For more information about override specifiers, see [override Specifier](../cpp/override-specifier.md) and [Override Specifiers and Native Compilations](../dotnet/how-to-declare-override-specifiers-in-native-compilations-cpp-cli.md).
2121

2222
For more information about context-sensitive keywords, see [Context-Sensitive Keywords](../windows/context-sensitive-keywords-cpp-component-extensions.md).
2323

2424
## Examples
25-
**Example**
2625

27-
The following code example shows that `override` can also be used in native compilations.
26+
The following code example shows that **override** can also be used in native compilations.
2827

29-
```cpp#
28+
```cpp
3029
// override_keyword_1.cpp
3130
// compile with: /c
3231
struct I1 {
@@ -38,11 +37,11 @@ struct X : public I1 {
3837
};
3938
```
4039
41-
**Example**
40+
### Example
41+
42+
The following code example shows that **override** can be used in Windows Runtime compilations.
4243
43-
The following code example shows that `override` can be used in Windows Runtime compilations.
44-
45-
```cpp#
44+
```cpp
4645
// override_keyword_2.cpp
4746
// compile with: /ZW /c
4847
ref struct I1 {
@@ -54,15 +53,15 @@ ref struct X : public I1 {
5453
};
5554
```
5655

57-
**Requirements**
58-
59-
Compiler option: **/ZW**
60-
61-
**Example**
56+
#### Requirements
6257

63-
The following code example shows that `override` can be used in common language runtime compilations.
58+
Compiler option: `/ZW`
59+
60+
### Example
61+
62+
The following code example shows that **override** can be used in common language runtime compilations.
6463

65-
```cpp#
64+
```cpp
6665
// override_keyword_3.cpp
6766
// compile with: /clr /c
6867
ref struct I1 {
@@ -74,9 +73,9 @@ ref struct X : public I1 {
7473
};
7574
```
7675
77-
**Requirements**
76+
#### Requirements
7877
79-
Compiler option: **/clr**
78+
Compiler option: `/clr`
8079
8180
## See Also
8281
[override Specifier](../cpp/override-specifier.md)

‎docs/windows/override-specifiers-cpp-component-extensions.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ ms.workload: ["cplusplus", "uwp"]
1515
*Override specifiers* modify how inherited types and members of inherited types behave in derived types.
1616

1717
## All Runtimes
18-
**Remarks**
18+
### Remarks
1919

2020
For more information about override specifiers, see:
2121

@@ -29,21 +29,21 @@ ms.workload: ["cplusplus", "uwp"]
2929

3030
- [Override Specifiers and Native Compilations](../dotnet/how-to-declare-override-specifiers-in-native-compilations-cpp-cli.md)
3131

32-
`abstract` and `sealed` are also valid on type declarations, where they do not act as override specifiers.
32+
**abstract** and **sealed** are also valid on type declarations, where they do not act as override specifiers.
3333

3434
For information about explicitly overriding base class functions, see [Explicit Overrides](../windows/explicit-overrides-cpp-component-extensions.md).
3535

3636
## Windows Runtime
3737
(There are no remarks for this language feature that apply to only the Windows Runtime.)
3838

3939
### Requirements
40-
Compiler option: **/ZW**
40+
Compiler option: `/ZW`
4141

4242
## Common Language Runtime
4343
(There are no remarks for this language feature that apply to only the common language runtime.)
4444

4545
### Requirements
46-
Compiler option: **/clr**
46+
Compiler option: `/clr`
4747

4848
## See Also
4949
[Component Extensions for Runtime Platforms](../windows/component-extensions-for-runtime-platforms.md)

‎docs/windows/overview-of-generics-in-visual-cpp.md‎

Lines changed: 34 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -18,75 +18,69 @@ Generics are parameterized types supported by the common language runtime. A par
1818
C++ supports templates and both templates and generics support parameterized types to create typed collection classes. However, templates provide compile-time parameterization. You cannot reference an assembly containing a template definition and create new specializations of the template. Once compiled, a specialized template looks like any other class or method. In contrast, generics are emitted in MSIL as a parameterized type known by the runtime to be a parameterized type; source code that references an assembly containing a generic type can create specializations of the generic type. For more information on the comparison of Visual C++ templates and generics, see [Generics and Templates (Visual C++)](../windows/generics-and-templates-visual-cpp.md).
1919

2020
## Generic Functions and Types
21-
Class types, as long as they are managed types, may be generic. An example of this might be a `List` class. The type of an object in the list would be the type parameter. If you needed a `List` class for many different types of objects, before generics you might have used a `List` that takes **System::Object** as the item type. But that would allow any object (including objects of the wrong type) to be used in the list. Such a list would be called an untyped collection class. At best, you could check the type at runtime and throw an exception. Or, you might have used a template, which would lose its generic quality once compiled into an assembly. Consumers of your assembly could not create their own specializations of the template. Generics allow you to create typed collection classes, say `List<int>` (read as "List of int") and `List<double>` ("List of double") which would generate a compile-time error if you tried to put a type that the collection was not designed to accept into the typed collection. In addition, these types remain generic after they are compiled.
21+
Class types, as long as they are managed types, may be generic. An example of this might be a `List` class. The type of an object in the list would be the type parameter. If you needed a `List` class for many different types of objects, before generics you might have used a `List` that takes `System::Object` as the item type. But that would allow any object (including objects of the wrong type) to be used in the list. Such a list would be called an untyped collection class. At best, you could check the type at runtime and throw an exception. Or, you might have used a template, which would lose its generic quality once compiled into an assembly. Consumers of your assembly could not create their own specializations of the template. Generics allow you to create typed collection classes, say `List<int>` (read as "List of int") and `List<double>` ("List of double") which would generate a compile-time error if you tried to put a type that the collection was not designed to accept into the typed collection. In addition, these types remain generic after they are compiled.
2222

23-
A description of the syntax of generic classes may be found in [Generic Classes (C++/CLI)](../windows/generic-classes-cpp-cli.md)`.` A new namespace, <xref:System.Collections.Generic>, introduces a set of parameterized collection types including <xref:System.Collections.Generic.Dictionary%602>, <xref:System.Collections.Generic.List%601> and <xref:System.Collections.Generic.LinkedList%601>.
23+
A description of the syntax of generic classes may be found in [Generic Classes (C++/CLI)](../windows/generic-classes-cpp-cli.md). A new namespace, <xref:System.Collections.Generic>, introduces a set of parameterized collection types including <xref:System.Collections.Generic.Dictionary%602>, <xref:System.Collections.Generic.List%601> and <xref:System.Collections.Generic.LinkedList%601>.
2424

25-
Both instance and static class member functions, delegates, and global functions may also be generic. Generic functions may be necessary if the function's parameters are of an unknown type, or if the function itself must work with generic types. In many cases where **System::Object** may have been used in the past as a parameter for an unknown object type, a generic type parameter may be used instead, allowing for more type-safe code. Any attempt to pass in a type that the function was not designed for would be flagged as an error at compile time. Using **System::Object** as a function parameter, the inadvertent passing of an object that the function wasn't intended to deal with would not be detected, and you would have to cast the unknown object type to a specific type in the function body, and account for the possibility of an InvalidCastException. With a generic, code attempting to pass an object to the function would cause a type conflict so the function body is guaranteed to have the correct type.
25+
Both instance and static class member functions, delegates, and global functions may also be generic. Generic functions may be necessary if the function's parameters are of an unknown type, or if the function itself must work with generic types. In many cases where `System::Object` may have been used in the past as a parameter for an unknown object type, a generic type parameter may be used instead, allowing for more type-safe code. Any attempt to pass in a type that the function was not designed for would be flagged as an error at compile time. Using `System::Object` as a function parameter, the inadvertent passing of an object that the function wasn't intended to deal with would not be detected, and you would have to cast the unknown object type to a specific type in the function body, and account for the possibility of an InvalidCastException. With a generic, code attempting to pass an object to the function would cause a type conflict so the function body is guaranteed to have the correct type.
2626

27-
The same benefits apply to collection classes built on generics. Collection classes in the past would use **System::Object** to store elements in a collection. Insertion of objects of a type that the collection was not designed for was not flagged at compile time, and often not even when the objects were inserted. Usually, an object would be cast to some other type when it was accessed in the collection. Only when the cast failed would the unexpected type be detected. Generics solves this problem at compile time by detecting any code that inserts a type that doesn't match (or implicitly convert to) the type parameter of the generic collection.
27+
The same benefits apply to collection classes built on generics. Collection classes in the past would use `System::Object` to store elements in a collection. Insertion of objects of a type that the collection was not designed for was not flagged at compile time, and often not even when the objects were inserted. Usually, an object would be cast to some other type when it was accessed in the collection. Only when the cast failed would the unexpected type be detected. Generics solves this problem at compile time by detecting any code that inserts a type that doesn't match (or implicitly convert to) the type parameter of the generic collection.
2828

2929
For a description of the syntax, see [Generic Functions (C++/CLI)](../windows/generic-functions-cpp-cli.md).
3030

3131
## Terminology Used With Generics
3232

33-
##### Type Parameters
34-
A generic declaration contains one or more unknown types known as *type parameters*. Type parameters are given a name which stands for the type within the body of the generic declaration. The type parameter is used as a type within the body of the generic declaration. The generic declaration for List<T\> contains the type parameter T.
33+
### Type Parameters
34+
A generic declaration contains one or more unknown types known as *type parameters*. Type parameters are given a name which stands for the type within the body of the generic declaration. The type parameter is used as a type within the body of the generic declaration. The generic declaration for `List<T>` contains the type parameter T.
3535

36-
##### Type Arguments
37-
The *type argument* is the actual type used in place of the type parameter when the generic is specialized for a specific type or types. For example, `int` is the type argument in `List<int>`. Value types and handle types are the only types allowed in as a generic type argument.
36+
### Type Arguments
37+
The *type argument* is the actual type used in place of the type parameter when the generic is specialized for a specific type or types. For example, **int** is the type argument in `List<int>`. Value types and handle types are the only types allowed in as a generic type argument.
3838

39-
##### Constructed Type
39+
### Constructed Type
4040
A type constructed from a generic type is referred to as a *constructed type*. A type not fully specified, such as `List<T>` is an *open constructed type*; a type fully specified, such as `List<double>,` is a *closed constructed type* or *specialized type*. Open constructed types may be used in the definition of other generic types or methods and may not be fully specified until the enclosing generic is itself specified. For example, the following is a use of an open constructed type as a base class for a generic:
4141

42-
`// generics_overview.cpp`
43-
44-
`// compile with: /clr /c`
45-
46-
`generic <typename T>`
42+
```cpp
43+
// generics_overview.cpp
44+
// compile with: /clr /c
45+
generic <typename T>
4746

48-
`ref class List {};`
47+
ref class List {};
4948

50-
`generic <typename T>`
49+
generic <typename T>
5150

52-
`ref class Queue : public List<T> {};`
51+
ref class Queue : public List<T> {};
52+
```
5353
54-
##### Constraint
54+
### Constraint
5555
A constraint is a restriction on the types that may be used as a type parameter. For example, a given generic class could accept only classes that inherit from a specified class, or implement a specified interface. For more information, see [Constraints on Generic Type Parameters (C++/CLI)](../windows/constraints-on-generic-type-parameters-cpp-cli.md).
5656
5757
## Reference Types and Value Types
58-
Handles types and value types may be used as type arguments. In the generic definition, in which either type may be used, the syntax is that of reference types. For example, the **->** operator is used to access members of the type of the type parameter whether or not the type eventually used is a reference type or a value type. When a value type is used as the type argument, the runtime generates code that uses the value types directly without boxing the value types.
58+
Handles types and value types may be used as type arguments. In the generic definition, in which either type may be used, the syntax is that of reference types. For example, the `->` operator is used to access members of the type of the type parameter whether or not the type eventually used is a reference type or a value type. When a value type is used as the type argument, the runtime generates code that uses the value types directly without boxing the value types.
5959
6060
When using a reference type as a generic type argument, use the handle syntax. When using a value type as a generic type argument, use the name of the type directly.
6161
62-
`// generics_overview_2.cpp`
63-
64-
`// compile with: /clr`
65-
66-
`generic <typename T>`
67-
68-
`ref class GenericType {};`
69-
70-
`ref class ReferenceType {};`
71-
72-
`value struct ValueType {};`
73-
74-
`int main() {`
62+
```cpp
63+
// generics_overview_2.cpp
64+
// compile with: /clr
65+
generic <typename T>
7566
76-
`GenericType<ReferenceType^> x;`
67+
ref class GenericType {};
68+
ref class ReferenceType {};
7769
78-
`GenericType<ValueType> y;`
70+
value struct ValueType {};
7971
80-
`}`
72+
int main() {
73+
GenericType<ReferenceType^> x;
74+
GenericType<ValueType> y;
75+
}
76+
```
8177

8278
## Type Parameters
8379
Type parameters in a generic class are treated like other identifiers. However, because the type is not known, there are restrictions on their use. For example, you cannot use members and methods of the type parameter class unless the type parameter is known to support these members. That is, to access a member through the type parameter, you must add the type that contains the member to the type parameter's constraint list.
8480

85-
`// generics_overview_3.cpp`
86-
87-
`// compile with: /clr`
88-
89-
```
81+
```cpp
82+
// generics_overview_3.cpp
83+
// compile with: /clr
9084
interface class I {
9185
void f1();
9286
void f2();

0 commit comments

Comments
 (0)