mcs/class/doc/API-notes

   1 Please add your comments to this file about mismatches between the API
   2 documentation and the implementation in the Microsoft or ECMA implementations
   3 of the class libraries.
   4
   5 * Type.GetCustomAttributes(Type, bool)
   6
   7         Documentation does not mention that an ArgumentNullException is
   8         thrown if Type is a null value.
   9
  10 * Rectangle.IsEmpty and  RectangleF.IsEmpty
  11
  12         Documentation says "This property returns true if the Width, Height, X,
  13         and Y properties of this RectangleF all have values of zero; otherwise,
  14         false." Reality: returns TRUE if width or height are equal 0.
  15
  16 * Array.CreateInstance (Type, long[] lengths)
  17
  18         Docs say if lengths is null, it will throw an ArgumentNullException,
  19         but actually .NET 1.1 throws a NullReferenceException.
  20
  21 * String Constructor (Char[], Int32, Int32):
  22
  23         String s = new String ((char[])null, 0, 0) throws a null, but the docs
  24         say it shouldn't.
  25
  26 * File.Exists:
  27
  28         File.Exists(null) returns false whenever there is a problem with the
  29         path or permissions.  This is a security feature which prevents the
  30         abuse of this method to discover what files might exist on the sytem.
  31         This doc error has been confirmed with MS and should be fixed in
  32         the next version of the docs.
  33
  34 * SocketPermission.IsSubsetOf:
  35
  36         10.11.4.* IsSubsetOf 10.11.*.* returns false --> which is incorrect
  37
  38 * SecurityElement.IsValid* ():
  39
  40         All return incorrect results. E.g. IsValidTag ("&") returns true while
  41         it should be false and IsValidAttributeValue ("1 >= 2") returns false
  42         while this should be true.
  43
  44 * SocketPermission.Union (null):
  45
  46         Doesn't throw an ArgumentNullException.
  47
  48 * System.Net.Cookie.Value:
  49
  50         Spec says property cannot accept the semicolon and comma characters,
  51         yet it does.
  52
  53 * System.Net.Cookie.Domain:
  54
  55         Setting this property has no effect on ToString
  56
  57 * System.Net.Cookie Path:
  58
  59         Setting this property has no effect on ToString
  60
  61 * System.Net.CookieCollection:
  62
  63         The ReadOnly property has a getter only, which always returns true.
  64         Yet you can always add Cookie's.
  65
  66 * Array.IList.Contains(object):
  67         Throws an exception when called on a multi-dimensional array. Docs
  68         do not say this. Similar to Array.IList.IndexOf(object).
  69
  70 * Version.CompareTo(null):
  71
  72         Does not throw an exception. Any version compared to null is
  73         considered to be subsequent to null.
  74
  75 * BitConverter.To*():
  76
  77         The docs say it should be ArgumentOutOfRangeException in the
  78         case where "startIndex is less than zero or greater than the
  79         length of value minus 2.", but the mscorlib throws an
  80         ArgumentException.
  81
  82 * Guid.Guid(string) ctor:
  83
  84         The documentation says this ctor accepts (amongst others) the format
  85         "{0xdddddddd,0xdddd,0xdddd,{0xdd},{0xdd},{0xdd},{0xdd},{0xdd},{0xdd},
  86         {0xdd},{0xdd}}". As implemented in mscorlib, however, it accepts:
  87         "{0xdddddddd,0xdddd,0xdddd,{0xdd,0xdd,0xdd,0xdd,0xdd,0xdd,0xdd,0xdd}.
  88
  89 * Guid.ToString(string format):
  90
  91         The documentation specifies that if the format is the empty
  92         string or null, this is equivalant to a format "N". In
  93         mscorlib, the format "D" is taken here.
  94
  95 * String.Compare (String, Int32, String, Int32, Int32):
  96
  97         The documentation is a bit confusing.
  98
  99         In the "Remarks" section it says
 100
 101         >> The number of characters compared is the lesser of the length of
 102            strA less indexA, the length of strB less indexB, and length.
 103
 104         In the "Exception" section it says a condition for the
 105         ArgumentOutOfRangeException
 106
 107         >> The sum of indexA and length is greater than strA. Length.
 108         >> -or-
 109         >> The sum of indexB and length is greater than strB. Length.
 110         >> -or-
 111         >> indexA, indexB, or length is negative.
 112
 113         The latter implies that Compare ("ab", 0, "abcdef", 0, 3) will
 114         throw an exception - but the "Remarks" section implies that it will
 115         not. Both mscorlib.dll and our class libraries behave according to
 116         the "Remarks" section.
 117
 118 * TypeBuilder.GetInterfaces
 119
 120         This method does not return all the interfaces as documented,
 121         it only returns the interfaces that are implemented by this
 122         class, but not the interfaces that are exposed by the parent
 123         classes
 124
 125 * Array.CopyTo (Array, int).
 126
 127         According to the documentation, an ArgumentException is thrown
 128         if either "index is equal to or larger than the size of the
 129         array" or "the number of elements in the source array is
 130         greater than the available space from index to the end of the
 131         destination array".
 132
 133         The first condition is wrong, an exception is not thrown if
 134         index is equal to the length of array, but the source array
 135         contains zero elements:
 136
 137            int[] src = new int [0];
 138            int[] dest = new int [0];
 139            src.CopyTo (dest, 0)
 140
 141 * Assembly.Load (string)
 142
 143         The documentation states that the argument is the 'display name'
 144         of an assembly (eg 'System.Data') but since v1 this method will
 145         only successfully load an assembly if a full reference is given.
 146         The docs even give the following example:
 147
 148                 Assembly SampleAssembly;
 149                 // Load the assembly by providing the type name.
 150                 SampleAssembly = Assembly.Load("System.Data");
 151
 152         which fails with a FileNotFoundException. Apparently the method
 153         to use for loading an assembly given a display name is
 154         Assembly.LoadWithPartialName (string).
 155
 156 * SortedList.Clear ()
 157
 158         The documentation claims that the Capacity of the sorted list
 159         will not change, but it does.
 160
 161 * StringBuilder.Insert (int index, string value, int count)
 162
 163         It throws an exception for count < 1 instead of count < 0, which
 164         is what ECMA says.
 165