mono/web/class-library

* The Class Library

	The Class Library should be compatible with Microsoft's .NET
	implementation.

	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:[email protected]">[email protected]</a>
   	with the class you want to implement and CC <a
	href="mailto:[email protected]">[email protected]</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 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 (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
	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. 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

	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

	We will provide a new namespace to use GNOME specific features
	as well as a namespace to host Bonobo interfaces and classes
	in Mono.  

** Licensing

	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.

** Class Library testing

	We need to write regression tests that will verify
	the correctness of the class library, compiler, and JIT
	engine.

	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.