[Mono-devel-list] Re: Patch for full-featured mcs /doc support; without patch

[Atsushi Eno]

Hello,

Thanks for several comments.

Gaurav Vaish wrote:
> Hi Atsushi,
> 
>   Great work! Some comments:
> 
>   In decl.cs
> 
> + // strip 'T:' 'M:' 'F:' 'P:' 'E:' etc.
> + // Here, MS ignores its member kind. No idea why.
> + if (cref.Length > 2 && cref [1] == ':')
> +   signature = cref.Substring (2).Trim (wsChars);
> + else
> +   signature = cref;
> 
>   I am not sure, but the reason that I see is that the only place
> where discrepancy can be when there's a property name that clashes
> with a data-type. However, it will also mean that there's an inner
> class/enum/struct/blah with the same name as property which is not
> allowed.
> 
>   So, it is safe to assume that during searching, you can live without "F:" etc.

Hrm, so I think "thus" those prefixes are required to target what
the documentor wants to indicate. It might result in unexpected
references that mixes fields and inner classes in documents.

(Oh, so I wonder how ndoc handles it.)

>   public void SomeMethod(string /** <summary>Interesting</summary> */
> param1) {... }
> 
>   or
> 
>   public /// <remarks>something</remarks>
>         void /// <summary>Very very interesting </summary>
>      ThisIsInteresting() { ...}

I have some tests like them in "errors" archive: cs1587-14.cs and
cs1587-24.cs.

> <snip from="cs-parser.jay">
> : opt_attributes
>   opt_modifiers
>   type namespace_or_type_name
> +  {
> +   tmpComment = Lexer.consume_doc_comment ();
> +   Lexer.doc_state = XmlCommentState.NG;
> + }
> </snip>
> 
>   I couldn't locate it as a test-case. From what it seems to me
> currently, it may pickup the comments... but not quite sure.
> 
>   IMO, if it picks up these comments, move the collection of the
> comments to "opt_attributes" or ... well, I also faced this issue.
> Right now, I don't have the code with me... don't recall how I handled
> it. I can get back on this if required.

Mhm, yes, you are right. Well, as for opt_modifiers, since I set
NG state when modifier keyword appeared in cs-tokenizer.cs, the
check should be no problem.

So I tried csc with this test source for opt_attributes:

--------
// Compiler options: -doc:dummy.xml -warnaserror -warn:2
using System;

namespace TopNS
{
	/// test
	public class Foo
	{
		/// foo
		[/** oh? */CLSCompliant/** ooh!? */(false)] /** wow!! */
		public uint NonCLSField;
	}
}
--------

In fact it did not complain ;-)

Anyways, I'll add some more testcases for properties and fields
in errors.

>   The code otherwise looks pretty ok. I also learnt a few things from
> your code that I may directly borrow for my doc-engine. :-)

:-)

Atsushi Eno