dotnet / dotnet/dotnet-api-docs

XmlBinaryWriterSession.TryAdd: incorrect description of return values

Open
#8,656 2 comments 2 reactions 0 assignees View on GitHub
area-Serialization Pri3 untriaged
Dominant language
C#
Stars
949
Forks
1.7k
Avg merge
3d 27m
Merged PRs (30d)
49

Description

[Link to the documentation](https://learn.microsoft.com/en-us/dotnet/api/system.xml.xmlbinarywritersession.tryadd?view=net-7.0)

The description of return values is as follows:

> Returns
> Boolean
> **true** if the string could be added; otherwise, **false**.

But in fact the `TryAdd` method never returns `false`.

The code:
```csharp
public virtual bool TryAdd(XmlDictionaryString value, out int key)
{
ArgumentNullException.ThrowIfNull(value);

IntArray? keys;

if (_maps.TryGetValue(value.Dictionary, out keys))
{
key = (keys[value.Key] - 1);

if (key != -1)
{
// If the key is already set, then something is wrong
throw System.Runtime.Serialization.DiagnosticUtility.ExceptionUtility.ThrowHelperError(new InvalidOperationException(SR.XmlKeyAlreadyExists));
}

key = Add(value.Value);
keys[value.Key] = (key + 1);
return true;
}

key = Add(value.Value);
keys = AddKeys(value.Dictionary, value.Key + 1);
keys[value.Key] = (key + 1);
return true;
}
```

[Link to the sources](https://github.com/dotnet/runtime/blob/d099f075e45d2aa6007a22b71b45a08758559f80/src/libraries/System.Private.DataContractSerialization/src/System/Xml/XmlBinaryWriterSession.cs#L28)

The `TryAdd` method returns `true` or throws an exception, but it doesn't return `false`.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.