Add FS-1027 (#75)

Co-authored-by: Edgar Gonzalez <[email protected]>

Author: roboz0r

spec/rfc-status.md

@@ -31,7 +31,7 @@
 | F# 4.1 | FS-1019 | [Implicitly Add the Module Suffix](https://github.com/fsharp/fslang-design/tree/main/FSharp-4.1/FS-1019-implicitly-add-the-module-suffix.md) | [completed](https://github.com/fsharp/fslang-spec/pull/77) |
 | F# 4.1 | FS-1020 | [ByRef Returns](https://github.com/fsharp/fslang-design/tree/main/FSharp-4.1/FS-1020-byref-returns.md) | |
 | F# 4.1 | FS-1025 | [Improve Record Type Inference](https://github.com/fsharp/fslang-design/tree/main/FSharp-4.1/FS-1025-improve-record-type-inference.md) | |
-| F# 4.1 | FS-1027 | [Complete Optional DefaultParameterValue](https://github.com/fsharp/fslang-design/tree/main/FSharp-4.1/FS-1027-complete-optional-defaultparametervalue.md) | |
+| F# 4.1 | FS-1027 | [Complete Optional DefaultParameterValue](https://github.com/fsharp/fslang-design/tree/main/FSharp-4.1/FS-1027-complete-optional-defaultparametervalue.md) | [completed](https://github.com/fsharp/fslang-spec/pull/75) |
 | F# 4.1 | FS-1029 | [Implement IReadOnlyCollection in list](https://github.com/fsharp/fslang-design/tree/main/FSharp-4.1/FS-1029-Implement%20IReadOnlyCollection%20in%20list.md) | |
 | F# 4.1 | FS-1040 | [Enum Match](https://github.com/fsharp/fslang-design/tree/main/FSharp-4.1/FS-1040-enum-match.md) | |
 | F# 4.5 | FS-1047 | [Match Bang](https://github.com/fsharp/fslang-design/tree/main/FSharp-4.5/FS-1047-match-bang.md) | [completed](https://github.com/fsharp/fslang-spec/pull/67) |

spec/special-attributes-and-types.md

@@ -32,11 +32,12 @@ assemblies that are authored in other CLI languages.
 | System.Runtime.CompilerServices.InternalsVisibleToAttribute `[<InternalsVisibleTo(...)>]` | Directs the F# compiler to permit access to the internals of the assembly. <br>This attribute may be used in both F# and imported assemblies. |
 | System.Runtime.CompilerServices.TypeForwardedToAttribute `[<TypeForwardedTo(...)>]` | Indicates a type redirection. <br>This attribute may be used only in imported non-F# assemblies. It is not permitted in F# code. |
 | System.Runtime.CompilerServices.ExtensionAttribute <br> `[<Extension(...)>]` | Indicates the compiled form of a C# extension member. <br>This attribute may be used only in imported non-F# assemblies. It is not permitted in F# code. |
+| System.Runtime.InteropServices.DefaultParameterValueAttribute <br> `[<DefaultParameterValue(...)>]` | When applied to a parameter in conjunction with the `[<Optional>]` attribute, specifies the default value to be inserted at the callsite. <br>This attribute may be used in both F# and imported assemblies. |
 | System.Runtime.InteropServices.DllImportAttribute <br> `[<DllImport(...)>]` | When applied to a function definition in a module, causes the F# compiler to ignore the implementation of the definition, and instead compile it as a CLI P/Invoke stub declaration. <br>This attribute may be used in both F# and imported assemblies. |
 | System.Runtime.InteropServices.MarshalAsAttribute <br> `[<MarshalAs(...)>]` | When applied to a parameter or return type, specifies the marshalling attribute for a CLI P/Invoke stub declaration. <br>This attribute may be used in both F# and imported assemblies. However, F# does not support the specification of "custom" marshallers. |
 | System.Runtime.InteropServices.InAttribute <br> `[<In>]` | When applied to a parameter, specifies the CLI In attribute. <br>This attribute may be used in both F# and imported assemblies. However, in F# its only effect is to change the corresponding attribute in the CLI compiled form. |
 | System.Runtime.InteropServices.OutAttribute <br> `[<Out>]` | When applied to a parameter, specifies the CLI Out attribute. <br>This attribute may be used in both F# and imported assemblies. However, in F# its only effect is to change the corresponding attribute in the CLI compiled form. |
-| System.Runtime.InteropServices.OptionalAttribute <br> `[<Optional(...)>]` | When applied to a parameter, specifies the CLI Optional attribute. <br>This attribute may be used in both F# and imported assemblies. However, in F# its only effect is to change the corresponding attribute in the CLI compiled form. |
+| System.Runtime.InteropServices.OptionalAttribute <br> `[<Optional(...)>]` | When applied to a parameter, specifies the CLI Optional attribute. Should be used in conjunction with `[<DefaultParameterValue(...)>]`. <br>This attribute may be used in both F# and imported assemblies. |
 | System.Runtime.InteropServices.FieldOffsetAttribute <br> `[<FieldOffset(...)>]` | When applied to a field, specifies the field offset of the underlying CLI field. <br>This attribute may be used in both F# and imported assemblies. |
 | System.NonSerializedAttribute <br> `[<NonSerialized>]` | When applied to a field, sets the "not serialized" bit for the underlying CLI field. <br>This attribute may be used in both F# and imported assemblies. |
 | System.Runtime.InteropServices.StructLayoutAttribute <br> `[<StructLayout(...)>]` | Specifies the layout of a CLI type. <br>This attribute may be used in both F# and imported assemblies. |

spec/type-definitions.md

@@ -1939,10 +1939,28 @@ type C =
 
 ### Optional Arguments to Method Members
 
-Method members—but not functions definitions—may have optional arguments. Optional
-arguments must appear at the end of the argument list. An optional argument is marked with a?
-before its name in the method declaration. Inside the member, the argument has type
-`option<argType>`.
+Method members—but not functions definitions—may have optional arguments. F# supports
+two forms of optional arguments: F#-style optional arguments and CLI-compatible optional arguments.
+
+CLI-compatible optional arguments are handled on the **caller side**. When a method call omits
+an optional argument, the compiler reads the default value from the method's metadata and
+explicitly passes that value. This contrasts with F#-style optional arguments, which are
+handled by the **callee**. With F#-style optional arguments, if an argument is omitted, the
+compiler passes `None`, and the callee determines the default value to use.
+
+From the caller's perspective both styles appear as optional arguments. However, their
+underlying mechanism and primary use cases differ.
+
+The compiled representation of members varies as additional optional arguments are added. The
+addition of optional arguments to a member signature results in a compiled form that is not binary-
+compatible with the previous compiled form.
+
+#### F\#-Style Optional Arguments
+
+F#-style optional arguments must appear at the end of the argument list. An optional argument
+is marked with a `?` before its name in the method declaration. Inside the member, the argument
+has the type `option<argType>`. The `option` type is used to represent a value that may or may
+not exist.
 
 The following example declares a method member that has two optional arguments:
 
@@ -1993,10 +2011,72 @@ The resolution of calls that use optional arguments is specified in _Method Appl
 
 Optional arguments may not be used in member constraints.
 
+Marking an argument as optional is equivalent to adding the `FSharp.Core.OptionalArgument`
+attribute ([§](special-attributes-and-types.md#custom-attributes-recognized-by-f)) to a required argument. This attribute is added implicitly for optional arguments.
+Adding the `[<OptionalArgument>]` attribute to a parameter of type `'a option` in a virtual method
+signature is equivalent to using the `(?x:'a)` syntax in a method definition. If the attribute is applied
+to an argument of a method, it should also be applied to all subsequent arguments of the method.
+Otherwise, it has no effect and callers must provide all of the arguments.
+
+#### CLI-Compatible Optional Arguments
+
+For interoperability with C# and other CLI languages, F# supports optional arguments with default values using
+the `Optional` and `DefaultParameterValue` attributes. This mechanism is equivalent to defining an optional
+argument in C# with a default value, such as `MyMethod(int i = 3)`. In F#, this would be written as:
+
+```fsharp
+open System.Runtime.InteropServices
+
+type C() =
+    static member MyMethod([<Optional; DefaultParameterValue(3)>] i: int) =
+        i + 1
+```
+
+These attributes are typically used for C# and VB interop so that callers in those languages see an argument as optional.
+They can also be from F# code in the same assembly and from separate assemblies.
+
+CLI-compatible optional arguments are not passed as values of type `Option<_>`. If the optional
+argument is present, its value is passed. If the optional argument is omitted, the default
+value from the CLI metadata is supplied instead. The value `System.Reflection.Missing.Value`
+is supplied for any CLI optional arguments of type `System.Object` that do not have a
+corresponding CLI default value, and the default (zero-bit pattern) value is supplied for
+other CLI optional arguments of other types that have no default value.
+
+##### Allowable Default Values
+
+The `DefaultParameterValue` attribute accepts the following types of values:
+
+- **Primitive Types**: Constant values for `sbyte`, `byte`, `int16`, `uint16`, `int32`, `uint32`, `int64`, `uint64`, `float32`, `float`, and `string`.
+- **Reference Types**: The only allowed default value is `null`.
+- **Value Types**: The only allowed default value is the default value of the struct.
+
+##### Usage and Considerations
+
+The value provided to `DefaultParameterValue` must match the parameter's type. A mismatch will generate a compiler warning, and both the `Optional` and `DefaultParameterValue` attributes will be ignored.
+
+For example, the following is not allowed:
+
+```fsharp
+type Class() =
+  static member Wrong([<Optional; DefaultParameterValue("string")>] i:int) = ()```
+
+This will be compiled as if it were written:
+```fsharp
+type Class() =
+  static member Wrong(i:int) = ()
+```
+
+Note that the `null` value for reference types must be type-annotated, for instance: `[<Optional; DefaultParameterValue(null:obj)>] o:obj`.
+
+It is possible to use these attributes in the following ways, though it is not standard practice:
+
+- Specifying `Optional` without `DefaultParameterValue`: Callers can omit the argument, and a default value will be chosen by convention (the default constructor for primitive types and structs).
+- Specifying `DefaultParameterValue` without `Optional`.
+- Specifying `Optional; DefaultParameterValue` on any parameter, not necessarily the last one.
+
 > Note : Imported CLI metadata may specify arguments as optional and may additionally
-specify a default value for the argument. These are treated as F# optional arguments. CLI
-optional arguments can propagate an existing optional value by name; for example,
-`?ValueTitle = Some (...)`.
+specify a default value for the argument. CLI optional arguments can propagate an existing optional
+value by name; for example, `?ValueTitle = Some (...)`.
 <br>For example, here is a fragment of a call to a Microsoft Excel COM automation API that
 uses named and optional arguments.
 
@@ -2010,25 +2090,6 @@ uses named and optional arguments.
                                   ValueTitle = "Sample Value Type")
 ```
 
-> CLI optional arguments are not passed as values of type `Option<_>`. If the optional
-argument is present, its value is passed. If the optional argument is omitted, the default
-value from the CLI metadata is supplied instead. The value
-`System.Reflection.Missing.Value` is supplied for any CLI optional arguments of type
-`System.Object` that do not have a corresponding CLI default value, and the default (zero-
-bit pattern) value is supplied for other CLI optional arguments of other types that have
-no default value.
-
-The compiled representation of members varies as additional optional arguments are added. The
-addition of optional arguments to a member signature results in a compiled form that is not binary-
-compatible with the previous compiled form.
-
-Marking an argument as optional is equivalent to adding the `FSharp.Core.OptionalArgument`
-attribute ([§](special-attributes-and-types.md#custom-attributes-recognized-by-f)) to a required argument. This attribute is added implicitly for optional arguments.
-Adding the `[<OptionalArgument>]` attribute to a parameter of type `'a option` in a virtual method
-signature is equivalent to using the `(?x:'a)` syntax in a method definition. If the attribute is applied
-to an argument of a method, it should also be applied to all subsequent arguments of the method.
-Otherwise, it has no effect and callers must provide all of the arguments.
-
 ### Type-directed Conversions at Member Invocations
 
 As described in _Method Application Resolution_ (see [§](inference-procedures.md#method-application-resolution)), three type-directed conversions are