XML comments for DbContext.Attach unclear

[nphmuller]

The current XML summary of DbContext.Attach:

Begins tracking the given entity in the Microsoft.EntityFrameworkCore.EntityState.Unchanged
state such that no operation will be performed when Microsoft.EntityFrameworkCore.DbContext.SaveChanges
is called.

A recursive search of the navigation properties will be performed to find reachable
entities that are not already being tracked by the context. These entities will
also begin to be tracked by the context. If a reachable entity has its primary
key value set then it will be tracked in the Microsoft.EntityFrameworkCore.EntityState.Unchanged
state. If the primary key value is not set then it will be tracked in the Microsoft.EntityFrameworkCore.EntityState.Added
state. An entity is considered to have its primary key value set if the primary
key property is set to anything other than the CLR default for the property type.

Use Microsoft.EntityFrameworkCore.ChangeTracking.EntityEntry.State to set the
state of only a single entity.

The first paragraph describes that the EntityState will always be set to Unchanged. But when the key is set it will actually be set to Added.

This behaviour is described in the second paragraph, but it's described in such a way that that only should be the case on navigation properties of the main entity. Apparently it's also the case for the main entity.

I think this behaviour is great, but the XML summary should specify that it also applies to the main entity.

Example:

var ctx = new MyContext();
var newOne = new MyEntity();
var newTwo = new MyEntity() { Id = 1 };
var newOneEntry = ctx.Attach(newOne);
var newTwoEntry = ctx.Attach(newTwo);

Console.WriteLine(newOneEntry.State); // Prints `Added`, although the docs describe it should be `Unchanged`.
Console.WriteLine(newTwoEntry.State); // Prints `Unchanged` as expected.

Further technical details

EF Core version: 2.1.4