[Mono-list] Re: [Mono-docs-list] WebControls Documentation

Miguel de Icaza miguel@ximian.com
07 Mar 2002 19:57:35 -0500


  I sent that email without finishing.

  Anyways, having 27-languages embedded in your source code, like this:

	/// <summary lang="en">
  	///   Returns the Name of this type
	/// </summary>
	/// <remarks lang="en">
	///   The type must be non-null, and you should make sure that
	///   the frobber has been properly initialized
	/// </remarks>
	/// <summary lang="es">
	///   Regresa el nombre de este tipo.
	/// </summary>
	/// <remarks lang="es>
	///   El tipo debe de tener un valor no-nulo, y el usuario debe
	///   de asegurarse que el frobber ha sido propiamente
	///   inicializado.
	/// </remarks>

	public string Name {
		get {
			return value;

   Those were two languages, now add 25 more.  

   I suggested to keep only english in the source code, and having the
translations in external files, but people who routinely maintain
translations of APIs complained heavily because this is a very hard way
of tracking documentation changes.  It was because of their experience
that we have decided to place the documentation externally.

    We could use the Microsoft XML DTD for the documentation, I have no
problem with this.  I am not sure if the documentation tools that John
outlined and that were later maintained by Adam are finished or complete
for this task, but we should find out.