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.
+