Typo in "Method Parameters" Documentation, at section "Combinations of parameter type and argument mode"

TeoPsycho commented 4 months ago

Type of issue

Typo

Description

In the third bullet of section "Combinations of parameter type and argument mode" (url = https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/method-parameters#combinations-of-parameter-type-and-argument-mode) there is a typo: "aren't" should be "are". The corrected paragraph should be:

When you pass a value type by reference:
- If the method assigns the parameter to refer to a different object, those changes ${\color{red}are}$ visible from the caller.
- If the method modifies the state of the object referred to by the parameter, those changes are visible from the caller.

Page URL

https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/method-parameters

Content source URL

https://github.com/dotnet/docs/blob/main/docs/csharp/language-reference/keywords/method-parameters.md

Document Version Independent Id

7241f712-8d73-b5e0-37c0-5f05c92412c6

Article author

@BillWagner

Metadata

ID: b8dd92fe-5053-1bc6-1c8f-cf9f88635cb5
Service: dotnet-csharp
Sub-service: lang-reference

Associated WorkItem - 335969

samwherever commented 4 months ago

hey! i i'm trying to start contributing to open source docs, so i can handle this if that's alright. just assign it to me if that's okay!

samwherever commented 4 months ago

Okay, hopefully I did this correctly! I made the changes and submitted a PR here.

BillWagner commented 4 months ago

Hi @TeoPsycho @samwherever

The current article is correct. I explained the distinction in #32853.

This has come up a few times, and it is a cause of confusion.

Maybe the better fix is to add examples for each of the bullet points?

TeoPsycho commented 4 months ago

In the documentation the example that follows the section of interest deals with a class, so it refers to the 4th bullet (pass a reference type by reference) and to the 1st sub-bullet (method assigns the parameter to refer to different object).

If in the example the class is changed to a struct object, since the struct object is a value type, it would refer to the 3rd bullet (pass a value type by reference) and to the 1st sub-bullet (method assigns the parameter to refer to different object) . Running the modified code the result would be that the changes are visible from the caller, just like the case with class object.

struct Product
{
    public Product(string name, int newID)
    {
        ItemName = name;
        ItemID = newID;
    }

    public string ItemName { get; set; }
    public int ItemID { get; set; }
}

private static void ChangeByReference(ref Product itemRef)
{
    // Change the address that is stored in the itemRef parameter.
    itemRef = new Product("Stapler", 12345);
}

private static void ModifyProductsByReference()
{
    // Declare an instance of Product and display its initial values.
    Product item = new Product("Fasteners", 54321);
    System.Console.WriteLine("Original values in Main.  Name: {0}, ID: {1}\n",
        item.ItemName, item.ItemID);

    // Pass the product instance to ChangeByReference.
    ChangeByReference(ref item);
    System.Console.WriteLine("Calling method.  Name: {0}, ID: {1}\n",
        item.ItemName, item.ItemID);
}

// This method displays the following output:
// Original values in Main.  Name: Fasteners, ID: 54321
// Calling method.  Name: Stapler, ID: 12345

To confirm once again that the struct object is a value type it can be demonstrated that the 1st bullet, 2nd sub-bullet is applicable to it (pass a value type by value and modify the state of the object). Then the changes would not be visible from the caller, as pointed in the documentation:

private static void ChangeByValue(Product itemVal)
{
    // Modify the state of the object that is stored in the itemVal parameter.
    itemVal.ItemName = "Hammer";
    itemVal.ItemID = 31415;
    System.Console.WriteLine("Values inside the method.  Name: {0}, ID: {1}\n",
        itemVal.ItemName, itemVal.ItemID);
}
private static void ModifyProductsByValue()
{
    // Declare an instance of Product and display its initial values.
    Product item = new Product("Fasteners", 54321);
    System.Console.WriteLine("Original values in Main.  Name: {0}, ID: {1}\n",
        item.ItemName, item.ItemID);

    // Pass the product instance to ChangeByValue.
    ChangeByValue(item);
    System.Console.WriteLine("Calling method.  Name: {0}, ID: {1}\n",
        item.ItemName, item.ItemID);
}

// This method displays the following output:
// Original values in Main.  Name: Fasteners, ID: 54321
// Values inside the method.  Name: Hammer, ID: 31415 
// Calling method.  Name: Fasteners, ID: 54321

BillWagner commented 2 weeks ago

I'm moving this out to November. As I tried to rewrite the bulleted lists, I think images will express these differences much better. I'm going to make some sketches and work with our art department and submit the PR next month.

dotnet / docs