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

[Miguel de Icaza]

Hello,

> It seems a shame to reinvent the wheel...
> 
> Is there any plan to support the '///'-style comments used by csc to
> generate this stuff?

Yes, we will support at some point the ///-style comments to generate
documentation in Mono, but we are talking about a different problem
here.

Although the in-line documentation is very useful in some cases (that is
why we will support the ///-style comments), the problem that we are
facing currently is that it does not work well if you are going to keep
track of documentation in 27 languages or so (that is the number of
languages that GNOME is routinely translated to for example).

Having 27 languages in XML comments for a property like this:

	string Name {
	}

> 
> Piers.
> 
> -----Original Message-----
> From: Miguel de Icaza [mailto:miguel@ximian.com
> <mailto:miguel@ximian.com> ] 
> Sent: Tuesday, March 05, 2002 11:39 AM
> To: Adam Treat
> Cc: Gaurav Vaish; mono-list@ximian.com; mono-docs-list@ximian.com
> Subject: Re: [Mono-list] Re: [Mono-docs-list] WebControls Documentation
> 
> 
> > I hate the idea of this holding up writing external documentation.  
> > While it
> > is true that the tools are not complete, if we can just come up with a
> 
> > standard DTD for the external documentation, then maybe we can get
> started 
> > actually writing the docs.  Below is the sample I was using for
> external 
> > documentation.  Another issue to think about is where to put the
> external 
> > docs.  
> 
> The DTD you posted seems good, there are some questions though, how do
> you list the various argument that the function takes, and provide
> examples?
> 
> There are a couple of options about placing documentation:
> 
> 	a) Create a `docs' dir on each directory containing source code,
> 	   and inside this `docs' directory, create a directory per
> 	   language (C, de, es, fr, etc).
> 
> 	   So something like:
> 
> 	      mcs/
> 		corlib/
> 			System/
> 				docs-es
> 					Byte.xml
> 
> 	b) Mirror the hierarchy:
> 
> 	    mcs/
> 		class/
> 			corlib/
> 				System/
> 					Byte.cs
> 		docs/
> 			corlib/
> 				System-es/
> 					Byte.cs
> 
> 	
> Miguel.
> 
> _______________________________________________
> Mono-list maillist  -  Mono-list@ximian.com
> http://lists.ximian.com/mailman/listinfo/mono-list
> <http://lists.ximian.com/mailman/listinfo/mono-list> 
> 
> _______________________________________________
> Mono-docs-list maillist  -  Mono-docs-list@ximian.com
> http://lists.ximian.com/mailman/listinfo/mono-docs-list