[Mono-list] Re: [Mono-hackers-list] Re: Patch for mcs

[Atsushi Eno]

Hi,

I decided to delay /doc patch for a while (it will be likely
two weeks or so in my current estimate)

	- To wait possible/actual problems raised by recent changes
	  (anonymous methods, System.dll breakage, build changes)
	- To *complete* the patch to avoid another large /doc patch
	- To clarify what Gaurav want and need to incorporate to mcs
	  and what is the same, differences, and conflicts in our
	  patches (yes, it conflicts; at least there is
	  MemberCore.Documentation in different types.)

Actually I've finished /** ... */ handling (heading '*') and
most of CS1587 warning (incorrect doc comment detection). The
large remaining task is 'cref' verification (and code
simplification).

I've put the patch here:
http://primates.ximian.com/~atsushi/mcs-doc-patches/mcs-doc-20041102.diff
and will post to the list when I finished cref handling.

Gaurav Vaish wrote:
>>Mhm, I cannot understand what you meant. What is (and should not be?)
>>discarded? My patch handles usual "/** ... */" comments as well as
>>those comments.
> 
> 
>   Well, you can only understand
> 
>   /**
>    * <summary>This is ok</summary>
>    */
> 
>  but not this. It will complain...
> 
>   /**
>    * Raw text is not ok.
>    */

No, it understands such markup (maybe you mean, comments without
tags?). Having XmlElement does not matter here. It is just a
cosmetic matter that we could just hold string and a few fields
instead of XmlElement.

>>When it comes to that you're just using the common markup to
>>csc /doc, why just not pipeline to ndoc(-console) or whatever?
> 
> 
>   Because they will not understand "extended" tags. My idea is to the
> built the infrastructure like that of Doclet and Taglet, hence I
> cannot simply pipeline.

Do you intend to create another tool like javadoc?

>>Well, such extensions should not be done with /doc switch. It should
>>be available in different switch name, for example /docx.
> 
> 
>   That's what mcsdoc is. But for that to happen, I should be able to
> get the raw comment, not XMLElement.

Am not sure /mcsdoc is good name which sounds like "it is the MCS
documentation format" without common understanding. So what is
the documentation format? (javadoc?) How does your patch fill
your need?

Atsushi Eno