dotnet / dotnet/dotnet-api-docs

Documentation contradicts itself

Open
#1,657 0 comments 0 reactions 0 assignees View on GitHub
area-System.Runtime dotnet-api/prod Pri2 untriaged
Dominant language
C#
Stars
949
Forks
1.7k
Avg merge
3d 27m
Merged PRs (30d)
49

Description

The first line says

> The exception that is thrown when an attempt is made to access an element of an array or collection with an index that is outside its bounds.

Under "Remarks" a series of examples follows. Of the five examples, three of them throw `IndexOutOfRangeException` and two throw `ArgumentOutOfRangeException`, including one which is explicitly introduced as

> If you forget to check whether the search operation found a match, the runtime throws an IndexOutOfRangeException exception, as shown in this example.

Since `ArgumentOutOfRangeException` is not a subtype of `IndexOutOfRangeException` the examples explicitly show that the documentation is wrong.

To some extent this is a product problem, as illustrated by my own example below, but the documentation would be more helpful if it clearly documented the complexities of the real world instead of contradicting itself. I seriously doubt that the product team would be willing to change something so fundamental after so much time, but the doc could be corrected with much less pain.

using System;
using System.Collections.Generic;

class Inconsistent {
static void Main(string[] args) {
object chars = "abcdef".ToCharArray();

try
{
var array = (char[])chars;
Console.WriteLine(array[-1]);
}
catch (Exception ex) { Console.WriteLine(ex.GetType().Name); }

try
{
var array = (IList<char>)chars;
Console.WriteLine(array[-1]);
}
catch (Exception ex) { Console.WriteLine(ex.GetType().Name); }
}
}

outputs

IndexOutOfRangeException
ArgumentOutOfRangeException

---
#### Document Details

⚠ *Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.*

* ID: e32ccb12-a1e2-6f9f-a626-837ae43d6902
* Version Independent ID: 1033266a-0616-dde9-7b1d-bc206496da2c
* Content: [IndexOutOfRangeException Class (System)](https://docs.microsoft.com/en-us/dotnet/api/system.indexoutofrangeexception?view=netframework-4.7.2)
* Content Source: [xml/System/IndexOutOfRangeException.xml](https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System/IndexOutOfRangeException.xml)
* Product: **dotnet-api**
* GitHub Login: @rpetrusha
* Microsoft Alias: **ronpet**

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.