X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=blobdiff_plain;f=doc%2Fclass-library;h=95b56cacf9dad6a37dbbd14c90d25a945ad0ece7;hb=d52f62f25a81096c068da2d6d2c3a5f12b22d247;hp=58302f32898345c0ae8d757a20b7a6609e0a7b54;hpb=aceaacc0abe56540c7f93bcf8d5050d087573a23;p=mono.git

diff --git a/doc/class-library b/doc/class-library
index 58302f32898..95b56cacf9d 100644
--- a/doc/class-library
+++ b/doc/class-library
@@ -1,52 +1,102 @@
 * The Class Library
 
 	The Class Library should be compatible with Microsoft's .NET
-	implementation.  
+	implementation.
 
-	Ideally as much code as possible should be written using C#.
-	In some cases we might either need to interface with code
-	written in C for large chunks of functionality (libart and
-	Gtk+ for example) or we would need to interface to the system
-	libraries (libc on Unix for networking functions for
-	example).  
+	Please see the <a href="class-status.html">Class Status</a>
+	page for a status of who is working on which classes.
+	
+	We will write as much code as possible in C#. We may need to
+	interface with code written in C to gain access to the
+	functionality of libraries like libart, Gtk+, and libc.
+
+** Contributing
+
+	We welcome contributions to the the Class Library.  To get
+	started, check the status page for information about which
+	APIs are being worked on, and how to get in touch with 
+	individual maintainers.  
+
+	If you want to work on a class, first check the <a
+	href="download.html">Classes Distribution</a> to see if it is
+	not implemented yet, if not, check the <a
+	href="class-status.html">Class Status</a> to see if someone is
+	already working on it, and maybe contact them.
+
+	If nobody is working on it, mail <a
+	href="mailto:mono-list@ximian.com">mono-list@ximian.com</a>
+   	with the class you want to implement and CC <a
+	href="mailto:miguel@ximian.com">miguel@ximian.com</a>.
+
+	You can also track live the activities of the Mono CVS module
+	by subscribing to the <a
+	href="http://lists.ximian.com/mailman/listinfo/mono-cvs-list">mono-cvs-list</a>
+
+
+** Missing features
+
+	Our class libraries miss some features, for example, most classes
+	do not implement the serialization bits at all, it would be a good
+	contribution to add this to each class.
+
+	This is a simple task, but it needs to be done in a compatible way
+	with the Microsoft.NET classes: using the same arguments to serialize
+	and reincarnate data.
+
+** Layout
+
+	The Class Library resides in the `mcs' module in the directoy
+	`class'.
+	
+	Each directory in the directory represents the assembly where
+	the code belongs to, and inside each directory we divide the
+	code based on the namespace they implement.
+
+	There are two cases when we should consider portability: when
+	we are dealing with a couple of classes only that differ from
+	system to system (Consider System.Net and System.IO for Win32
+	and Unix).  In those cases we will just place the files for
+	example on <t>corlib/System/System.IO/Unix-Console.cs</t> and
+	<t>corlib/System/System.IO/Win32-Console.cs</t>.
+
+	For classes that might differ more (for example, the
+	implementation of Windows.Forms), we might have different
+	directories altogether: <t>System.Windows.Forms/Win32</t>,
+	<t>System.Windows.Forms/Gtk+</t> and
+	<t>System.Windows.Forms/Cocoa</t>.
 
 ** Using existing components from GNOME.
 
 	Our current plan is to implement the GUI tools on top of
-	Gtk+.  The only problem is that applications from Windows
+	Gtk+.  The only obstacle here is that applications from Windows
 	might expect to be able to pull the HWND property from the
 	widgets and use PInvoke to call Windows functions.
 
 ** Class Library and Win32 dependencies.
 
 	There are a few spots where the Win32 foundation is exposed to
-	the class library (the HDC and HWND properties in the GDI+).
-	It seems from casual inspection that these can be safely
-	mapped to Gdk's GC and GdkWindow pointers without breaking anything.
+	the class library (for example, the HDC and HWND properties in
+	the GDI+). Casual inspection suggests that these can be
+	safely mapped to Gdk's GC and GdkWindow pointers without
+	breaking anything.
 
 	The only drawback is that support for PInvoke of Win32 code
-	wont be available.  If this is necessary it could be possible
-	in the future by reusing pieces of Wine, and probably using
-	Wine as our toolkit, but we think that this is not as
-	important as we will wrap GNOME elements in the meantime. 
+	won't be available.  An alternate solution would be to use
+	portions of Wine, or even to use Wine as our toolkit.
 
 *** Initial GDI+ and WinForms implementation
 
 	The initial implementation will use Gtk+ as the underlying
-	toolkit, but implementations for other windowing systems
-	should be possible (particularly thinking about PDA devices
-	here).
-
-	Since Gtk+ 2.0 has been ported to other windowing systems
-	other than X (frame buffer, Win32 and BeOS implementation
-	exist) it should cover most uses for most users.
-
+ 	toolkit. Since GTK+ has already been ported to many windowing
+	systems other than X (including frame buffer, Win32, and BeOS)
+	its use should cover most applications for most users. 
+	
 *** Database access
 
-	Implementing the ADO.NET functionality can be done through
-	reusing <a href="http://www.gnome-db.org">GNOME-DB</a> as
-	GNOME-DB was implemented precisely to provide an ADO-like
-	system for GNOME.
+	We will implement ADO.NET functionality by reusing <a
+	href="http://www.gnome-db.org">GNOME-DB</a>. This is an ideal
+	choice, since GNOME-DB was implemented precisely to provide an
+	ADO-like system for GNOME.
 
 *** Component Integration
 
@@ -56,18 +106,85 @@
 
 ** Licensing
 
-	The class library will be licensed under the terms of the GNU
-	LGPL.
+	The class library is being licensed under the terms of the 
+	<a
+	href="http://www.opensource.org/licenses/mit-license.html">MIT
+	license.</a>  This is the same license used by the X11 window
+	system.
 
-	We suggest that you assign the copyright of your work to the
-	GNOME Foundation or the Free Software Foundation to simplify
-	defending the code in case it is used inappropiately. 
+** Class Library testing
 
-** Contributing
+	We need to write regression tests that will verify
+	the correctness of the class library, compiler, and JIT
+	engine.
 
-	We welcome contributions to the the Class Library, you can
-	check the status page.  Our status page describes which APIs
-	are being worked on and the contact information for the
-	contributor.
+	Please write your regression tests using <a
+	href="http://nunit.sourceforge.net">NUnit</a>
 
-	
+** Coding conventions
+
+	Please follow the conventions on the ECMA specification (On
+	the Annex Partition) for your coding your libraries. 
+
+	Use 8 space tabs for writing your code (hopefully we can keep
+	this consistent).  If you are modifying someone else's code, try
+	to keep the coding style similar.
+
+	For a rationale on 8 space tabs, read Linus Torvald's Coding
+	Style guidelines in the Linux kernel source for a rationale. 
+
+*** Missing implementation bits
+
+	If you implement a class and you are missing implementation bits,
+	please put in the code the word "TODO" and a description of what
+	is missing to be implemented.
+
+*** Tagging buggy code
+
+	If there is a bug in your implementation tag the problem by using
+	the word "FIXME" in the code, together with a description of the 
+	problem.
+
+	Do not use XXX or obscure descriptions, because otherwise people
+	will not be able to understand what you mean.
+
+*** Tagging Lame specs
+
+	Sometimes the specification will be lame (consider Version.ToString (fieldCount)
+	where there is no way of knowing how many fields are available, making the API
+	not only stupid, but leading to unreliable code).
+
+	In those cases, use the keyword "LAMESPEC".
+
+** Namespaces
+
+	We are using a number of namespaces in the class libraries for
+	private classes when we need them, you are encouraged to use these:
+
+<pre>
+Mono
+ .Languages     // General Compiler classes
+   .CSharp      // Specific C# parsing/tokenizing classes
+   .MonoBASIC   // Specific VB.NET/MonoBASIC parsing/tokenizing classes
+   .Python      // Specific Python parsing/tokenizing classes
+ .Runtime
+   .LateBind    // General latebinding-support for MonoBASIC/Python
+   .MonoBASIC   // Specific runtime classes for MonoBASIC programs
+   .Python      // Specific runtime classes for Python programs
+ .Web
+   .UI
+     .Utils     // Gaurav utility classes
+</pre>
+
+** FAQ
+
+Frequently asked questions about the class library:
+
+Q: I am writing a new class that overrides one of the system classes,
+   and I am getting a 1595 warning from the compiler.  Should we use a
+   different namespace?
+
+A: There is a quick solution to the problem, you can pass the command
+   line argument /nowarn:1595 and this will effectively let you use
+   your implementation of the code, while overriding the ones from the
+   system assemblies.
\ No newline at end of file