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

[Piers Haken]

Might I suggest using the existing standard format that's generated by
"csc.exe /doc:<filename.xml>" ?

Here's the docs for the 'XML Documentation' feature:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csref/h
tml/vclrftagsfordocumentationcomments.asp
<http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csref/
html/vclrftagsfordocumentationcomments.asp> 

If you use this then you can make use of the already quite large
selection of tools available for managing this stuff. Most notably the
excellent Ndoc:
	http://ndoc.sourceforge.net/ <http://ndoc.sourceforge.net/> 

It seems a shame to reinvent the wheel...

Is there any plan to support the '///'-style comments used by csc to
generate this stuff?

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>