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

Adam Treat manyoso@yahoo.com
Tue, 5 Mar 2002 11:54:46 -0800 

> No reason that i can point to.  I haven't looked at the ouput of csc /doc
> but, if there is any problem in the future we can just use an xsl transform
> to put it in whatever form we wish.

Ok, i think i was misleading there.  The problem as i see it with 'csc /doc'; 
csc parses the source and generates xml which is analogous to what we want 
our docstub and docgen tools to do when combined.  That is we have need of 
_two_ DTD's that when combined will produce something like the output of 'csc 
/doc'.  The docstub tool will generate a file through reflection which stubs 
out the particulars of a type.  The extenal documenation is another matter.  
IMHO, the external documentation should contain just enough tags to identify 
the type and then the rest should be stuff like <summary></summary> and 
<remarks></remarks> basically, tags that can't be generated through 
reflection.  Now, if you look at 'csc /doc' output this is combined 
reflection information as well as embedded xml in the source.  After all of 
this is done, I think we should write a stylesheet which turns our combined 
stub/extern xml into 'csc /doc' xml for purposes of interop.

<stub_xml>				<extern_xml>			<mono_xml>
  <reflection_based_tags>	+	   <summary>		=	  <combined_tags>
  </reflection_based_tags		  	   </summary>			  </combined_tags>
</stub_xml>				</extern_xml>			</mono_xml>

And then we can do an xsl transform on <mono_xml> to turn it into
<csc_doc> or <html> or <some_other_xml>

Cheers,

Adam