diff options
Diffstat (limited to 'mcs/class/doc/API-notes')
-rw-r--r-- | mcs/class/doc/API-notes | 165 |
1 files changed, 165 insertions, 0 deletions
diff --git a/mcs/class/doc/API-notes b/mcs/class/doc/API-notes new file mode 100644 index 00000000000..8ec2a9a4b1a --- /dev/null +++ b/mcs/class/doc/API-notes @@ -0,0 +1,165 @@ +Please add your comments to this file about mismatches between the API +documentation and the implementation in the Microsoft or ECMA implementations +of the class libraries. + +* Type.GetCustomAttributes(Type, bool) + + Documentation does not mention that an ArgumentNullException is + thrown if Type is a null value. + +* Rectangle.IsEmpty and RectangleF.IsEmpty + + Documentation says "This property returns true if the Width, Height, X, + and Y properties of this RectangleF all have values of zero; otherwise, + false." Reality: returns TRUE if width or height are equal 0. + +* Array.CreateInstance (Type, long[] lengths) + + Docs say if lengths is null, it will throw an ArgumentNullException, + but actually .NET 1.1 throws a NullReferenceException. + +* String Constructor (Char[], Int32, Int32): + + String s = new String ((char[])null, 0, 0) throws a null, but the docs + say it shouldn't. + +* File.Exists: + + File.Exists(null) returns false whenever there is a problem with the + path or permissions. This is a security feature which prevents the + abuse of this method to discover what files might exist on the sytem. + This doc error has been confirmed with MS and should be fixed in + the next version of the docs. + +* SocketPermission.IsSubsetOf: + + 10.11.4.* IsSubsetOf 10.11.*.* returns false --> which is incorrect + +* SecurityElement.IsValid* (): + + All return incorrect results. E.g. IsValidTag ("&") returns true while + it should be false and IsValidAttributeValue ("1 >= 2") returns false + while this should be true. + +* SocketPermission.Union (null): + + Doesn't throw an ArgumentNullException. + +* System.Net.Cookie.Value: + + Spec says property cannot accept the semicolon and comma characters, + yet it does. + +* System.Net.Cookie.Domain: + + Setting this property has no effect on ToString + +* System.Net.Cookie Path: + + Setting this property has no effect on ToString + +* System.Net.CookieCollection: + + The ReadOnly property has a getter only, which always returns true. + Yet you can always add Cookie's. + +* Array.IList.Contains(object): + Throws an exception when called on a multi-dimensional array. Docs + do not say this. Similar to Array.IList.IndexOf(object). + +* Version.CompareTo(null): + + Does not throw an exception. Any version compared to null is + considered to be subsequent to null. + +* BitConverter.To*(): + + The docs say it should be ArgumentOutOfRangeException in the + case where "startIndex is less than zero or greater than the + length of value minus 2.", but the mscorlib throws an + ArgumentException. + +* Guid.Guid(string) ctor: + + The documentation says this ctor accepts (amongst others) the format + "{0xdddddddd,0xdddd,0xdddd,{0xdd},{0xdd},{0xdd},{0xdd},{0xdd},{0xdd}, + {0xdd},{0xdd}}". As implemented in mscorlib, however, it accepts: + "{0xdddddddd,0xdddd,0xdddd,{0xdd,0xdd,0xdd,0xdd,0xdd,0xdd,0xdd,0xdd}. + +* Guid.ToString(string format): + + The documentation specifies that if the format is the empty + string or null, this is equivalant to a format "N". In + mscorlib, the format "D" is taken here. + +* String.Compare (String, Int32, String, Int32, Int32): + + The documentation is a bit confusing. + + In the "Remarks" section it says + + >> The number of characters compared is the lesser of the length of + strA less indexA, the length of strB less indexB, and length. + + In the "Exception" section it says a condition for the + ArgumentOutOfRangeException + + >> The sum of indexA and length is greater than strA. Length. + >> -or- + >> The sum of indexB and length is greater than strB. Length. + >> -or- + >> indexA, indexB, or length is negative. + + The latter implies that Compare ("ab", 0, "abcdef", 0, 3) will + throw an exception - but the "Remarks" section implies that it will + not. Both mscorlib.dll and our class libraries behave according to + the "Remarks" section. + +* TypeBuilder.GetInterfaces + + This method does not return all the interfaces as documented, + it only returns the interfaces that are implemented by this + class, but not the interfaces that are exposed by the parent + classes + +* Array.CopyTo (Array, int). + + According to the documentation, an ArgumentException is thrown + if either "index is equal to or larger than the size of the + array" or "the number of elements in the source array is + greater than the available space from index to the end of the + destination array". + + The first condition is wrong, an exception is not thrown if + index is equal to the length of array, but the source array + contains zero elements: + + int[] src = new int [0]; + int[] dest = new int [0]; + src.CopyTo (dest, 0) + +* Assembly.Load (string) + + The documentation states that the argument is the 'display name' + of an assembly (eg 'System.Data') but since v1 this method will + only successfully load an assembly if a full reference is given. + The docs even give the following example: + + Assembly SampleAssembly; + // Load the assembly by providing the type name. + SampleAssembly = Assembly.Load("System.Data"); + + which fails with a FileNotFoundException. Apparently the method + to use for loading an assembly given a display name is + Assembly.LoadWithPartialName (string). + +* SortedList.Clear () + + The documentation claims that the Capacity of the sorted list + will not change, but it does. + +* StringBuilder.Insert (int index, string value, int count) + + It throws an exception for count < 1 instead of count < 0, which + is what ECMA says. + |