mcs/doc.cs

   1 //
   2 // doc.cs: Support for XML documentation comment.
   3 //
   4 // Author:
   5 //      Atsushi Enomoto <atsushi@ximian.com>
   6 //
   7 // Dual licensed under the terms of the MIT X11 or GNU GPL
   8 //
   9 // Copyright 2004 Novell, Inc.
  10 //
  11 //
  12
  13 using System;
  14 using System.Collections.Generic;
  15 using System.IO;
  16 using System.Reflection;
  17 using System.Reflection.Emit;
  18 using System.Runtime.CompilerServices;
  19 using System.Runtime.InteropServices;
  20 using System.Security;
  21 using System.Security.Permissions;
  22 using System.Text;
  23 using System.Xml;
  24
  25 using Mono.CompilerServices.SymbolWriter;
  26
  27 namespace Mono.CSharp {
  28
  29         //
  30         // Support class for XML documentation.
  31         //
  32         static class DocUtil
  33         {
  34                 // TypeContainer
  35
  36                 //
  37                 // Generates xml doc comments (if any), and if required,
  38                 // handle warning report.
  39                 //
  40                 internal static void GenerateTypeDocComment (TypeContainer t,
  41                         DeclSpace ds, Report Report)
  42                 {
  43                         GenerateDocComment (t, ds, Report);
  44
  45                         if (t.DefaultStaticConstructor != null)
  46                                 t.DefaultStaticConstructor.GenerateDocComment (t);
  47
  48                         if (t.InstanceConstructors != null)
  49                                 foreach (Constructor c in t.InstanceConstructors)
  50                                         c.GenerateDocComment (t);
  51
  52                         if (t.Types != null)
  53                                 foreach (TypeContainer tc in t.Types)
  54                                         tc.GenerateDocComment (t);
  55
  56                         if (t.Delegates != null)
  57                                 foreach (Delegate de in t.Delegates)
  58                                         de.GenerateDocComment (t);
  59
  60                         if (t.Constants != null)
  61                                 foreach (Const c in t.Constants)
  62                                         c.GenerateDocComment (t);
  63
  64                         if (t.Fields != null)
  65                                 foreach (FieldBase f in t.Fields)
  66                                         f.GenerateDocComment (t);
  67
  68                         if (t.Events != null)
  69                                 foreach (Event e in t.Events)
  70                                         e.GenerateDocComment (t);
  71
  72                         if (t.Indexers != null)
  73                                 foreach (Indexer ix in t.Indexers)
  74                                         ix.GenerateDocComment (t);
  75
  76                         if (t.Properties != null)
  77                                 foreach (Property p in t.Properties)
  78                                         p.GenerateDocComment (t);
  79
  80                         if (t.Methods != null)
  81                                 foreach (MethodOrOperator m in t.Methods)
  82                                         m.GenerateDocComment (t);
  83
  84                         if (t.Operators != null)
  85                                 foreach (Operator o in t.Operators)
  86                                         o.GenerateDocComment (t);
  87                 }
  88
  89                 // MemberCore
  90                 private static readonly string line_head =
  91                         Environment.NewLine + "            ";
  92
  93                 private static XmlNode GetDocCommentNode (MemberCore mc,
  94                         string name, Report Report)
  95                 {
  96                         // FIXME: It could be even optimizable as not
  97                         // to use XmlDocument. But anyways the nodes
  98                         // are not kept in memory.
  99                         XmlDocument doc = RootContext.Documentation.XmlDocumentation;
 100                         try {
 101                                 XmlElement el = doc.CreateElement ("member");
 102                                 el.SetAttribute ("name", name);
 103                                 string normalized = mc.DocComment;
 104                                 el.InnerXml = normalized;
 105                                 // csc keeps lines as written in the sources
 106                                 // and inserts formatting indentation (which
 107                                 // is different from XmlTextWriter.Formatting
 108                                 // one), but when a start tag contains an
 109                                 // endline, it joins the next line. We don't
 110                                 // have to follow such a hacky behavior.
 111                                 string [] split =
 112                                         normalized.Split ('\n');
 113                                 int j = 0;
 114                                 for (int i = 0; i < split.Length; i++) {
 115                                         string s = split [i].TrimEnd ();
 116                                         if (s.Length > 0)
 117                                                 split [j++] = s;
 118                                 }
 119                                 el.InnerXml = line_head + String.Join (
 120                                         line_head, split, 0, j);
 121                                 return el;
 122                         } catch (Exception ex) {
 123                                 Report.Warning (1570, 1, mc.Location, "XML comment on `{0}' has non-well-formed XML ({1})", name, ex.Message);
 124                                 XmlComment com = doc.CreateComment (String.Format ("FIXME: Invalid documentation markup was found for member {0}", name));
 125                                 return com;
 126                         }
 127                 }
 128
 129                 //
 130                 // Generates xml doc comments (if any), and if required,
 131                 // handle warning report.
 132                 //
 133                 internal static void GenerateDocComment (MemberCore mc,
 134                         DeclSpace ds, Report Report)
 135                 {
 136                         if (mc.DocComment != null) {
 137                                 string name = mc.GetDocCommentName (ds);
 138
 139                                 XmlNode n = GetDocCommentNode (mc, name, Report);
 140
 141                                 XmlElement el = n as XmlElement;
 142                                 if (el != null) {
 143                                         mc.OnGenerateDocComment (el);
 144
 145                                         // FIXME: it could be done with XmlReader
 146                                         XmlNodeList nl = n.SelectNodes (".//include");
 147                                         if (nl.Count > 0) {
 148                                                 // It could result in current node removal, so prepare another list to iterate.
 149                                                 var al = new List<XmlNode> (nl.Count);
 150                                                 foreach (XmlNode inc in nl)
 151                                                         al.Add (inc);
 152                                                 foreach (XmlElement inc in al)
 153                                                         if (!HandleInclude (mc, inc, Report))
 154                                                                 inc.ParentNode.RemoveChild (inc);
 155                                         }
 156
 157                                         // FIXME: it could be done with XmlReader
 158                                         DeclSpace ds_target = mc as DeclSpace;
 159                                         if (ds_target == null)
 160                                                 ds_target = ds;
 161
 162                                         foreach (XmlElement see in n.SelectNodes (".//see"))
 163                                                 HandleSee (mc, ds_target, see, Report);
 164                                         foreach (XmlElement seealso in n.SelectNodes (".//seealso"))
 165                                                 HandleSeeAlso (mc, ds_target, seealso ,Report);
 166                                         foreach (XmlElement see in n.SelectNodes (".//exception"))
 167                                                 HandleException (mc, ds_target, see, Report);
 168                                 }
 169
 170                                 n.WriteTo (RootContext.Documentation.XmlCommentOutput);
 171                         }
 172                         else if (mc.IsExposedFromAssembly ()) {
 173                                 Constructor c = mc as Constructor;
 174                                 if (c == null || !c.IsDefault ())
 175                                         Report.Warning (1591, 4, mc.Location,
 176                                                 "Missing XML comment for publicly visible type or member `{0}'", mc.GetSignatureForError ());
 177                         }
 178                 }
 179
 180                 //
 181                 // Processes "include" element. Check included file and
 182                 // embed the document content inside this documentation node.
 183                 //
 184                 private static bool HandleInclude (MemberCore mc, XmlElement el, Report Report)
 185                 {
 186                         bool keep_include_node = false;
 187                         string file = el.GetAttribute ("file");
 188                         string path = el.GetAttribute ("path");
 189                         if (file == "") {
 190                                 Report.Warning (1590, 1, mc.Location, "Invalid XML `include' element. Missing `file' attribute");
 191                                 el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" Include tag is invalid "), el);
 192                                 keep_include_node = true;
 193                         }
 194                         else if (path.Length == 0) {
 195                                 Report.Warning (1590, 1, mc.Location, "Invalid XML `include' element. Missing `path' attribute");
 196                                 el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" Include tag is invalid "), el);
 197                                 keep_include_node = true;
 198                         }
 199                         else {
 200                                 XmlDocument doc;
 201                                 if (!RootContext.Documentation.StoredDocuments.TryGetValue (file, out doc)) {
 202                                         try {
 203                                                 doc = new XmlDocument ();
 204                                                 doc.Load (file);
 205                                                 RootContext.Documentation.StoredDocuments.Add (file, doc);
 206                                         } catch (Exception) {
 207                                                 el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (String.Format (" Badly formed XML in at comment file `{0}': cannot be included ", file)), el);
 208                                                 Report.Warning (1592, 1, mc.Location, "Badly formed XML in included comments file -- `{0}'", file);
 209                                         }
 210                                 }
 211                                 if (doc != null) {
 212                                         try {
 213                                                 XmlNodeList nl = doc.SelectNodes (path);
 214                                                 if (nl.Count == 0) {
 215                                                         el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" No matching elements were found for the include tag embedded here. "), el);
 216
 217                                                         keep_include_node = true;
 218                                                 }
 219                                                 foreach (XmlNode n in nl)
 220                                                         el.ParentNode.InsertBefore (el.OwnerDocument.ImportNode (n, true), el);
 221                                         } catch (Exception ex) {
 222                                                 el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" Failed to insert some or all of included XML "), el);
 223                                                 Report.Warning (1589, 1, mc.Location, "Unable to include XML fragment `{0}' of file `{1}' ({2})", path, file, ex.Message);
 224                                         }
 225                                 }
 226                         }
 227                         return keep_include_node;
 228                 }
 229
 230                 //
 231                 // Handles <see> elements.
 232                 //
 233                 private static void HandleSee (MemberCore mc,
 234                         DeclSpace ds, XmlElement see, Report r)
 235                 {
 236                         HandleXrefCommon (mc, ds, see, r);
 237                 }
 238
 239                 //
 240                 // Handles <seealso> elements.
 241                 //
 242                 private static void HandleSeeAlso (MemberCore mc,
 243                         DeclSpace ds, XmlElement seealso, Report r)
 244                 {
 245                         HandleXrefCommon (mc, ds, seealso, r);
 246                 }
 247
 248                 //
 249                 // Handles <exception> elements.
 250                 //
 251                 private static void HandleException (MemberCore mc,
 252                         DeclSpace ds, XmlElement seealso, Report r)
 253                 {
 254                         HandleXrefCommon (mc, ds, seealso, r);
 255                 }
 256
 257                 static readonly char [] wsChars =
 258                         new char [] {' ', '\t', '\n', '\r'};
 259
 260                 //
 261                 // returns a full runtime type name from a name which might
 262                 // be C# specific type name.
 263                 //
 264                 private static Type FindDocumentedType (MemberCore mc, string name, DeclSpace ds, string cref, Report r)
 265                 {
 266                         bool is_array = false;
 267                         string identifier = name;
 268                         if (name [name.Length - 1] == ']') {
 269                                 string tmp = name.Substring (0, name.Length - 1).Trim (wsChars);
 270                                 if (tmp [tmp.Length - 1] == '[') {
 271                                         identifier = tmp.Substring (0, tmp.Length - 1).Trim (wsChars);
 272                                         is_array = true;
 273                                 }
 274                         }
 275                         Type t = FindDocumentedTypeNonArray (mc, identifier, ds, cref, r);
 276                         if (t != null && is_array)
 277                                 t = Array.CreateInstance (t, 0).GetType ();
 278                         return t;
 279                 }
 280
 281                 private static Type FindDocumentedTypeNonArray (MemberCore mc,
 282                         string identifier, DeclSpace ds, string cref, Report r)
 283                 {
 284                         switch (identifier) {
 285                         case "int":
 286                                 return TypeManager.int32_type;
 287                         case "uint":
 288                                 return TypeManager.uint32_type;
 289                         case "short":
 290                                 return TypeManager.short_type;;
 291                         case "ushort":
 292                                 return TypeManager.ushort_type;
 293                         case "long":
 294                                 return TypeManager.int64_type;
 295                         case "ulong":
 296                                 return TypeManager.uint64_type;;
 297                         case "float":
 298                                 return TypeManager.float_type;;
 299                         case "double":
 300                                 return TypeManager.double_type;
 301                         case "char":
 302                                 return TypeManager.char_type;;
 303                         case "decimal":
 304                                 return TypeManager.decimal_type;;
 305                         case "byte":
 306                                 return TypeManager.byte_type;;
 307                         case "sbyte":
 308                                 return TypeManager.sbyte_type;;
 309                         case "object":
 310                                 return TypeManager.object_type;;
 311                         case "bool":
 312                                 return TypeManager.bool_type;;
 313                         case "string":
 314                                 return TypeManager.string_type;;
 315                         case "void":
 316                                 return TypeManager.void_type;;
 317                         }
 318                         FullNamedExpression e = ds.LookupNamespaceOrType (identifier, mc.Location, false);
 319                         if (e != null) {
 320                                 if (!(e is TypeExpr))
 321                                         return null;
 322                                 return e.Type;
 323                         }
 324                         int index = identifier.LastIndexOf ('.');
 325                         if (index < 0)
 326                                 return null;
 327                         int warn;
 328                         Type parent = FindDocumentedType (mc, identifier.Substring (0, index), ds, cref, r);
 329                         if (parent == null)
 330                                 return null;
 331                         // no need to detect warning 419 here
 332                         return FindDocumentedMember (mc, parent,
 333                                 identifier.Substring (index + 1),
 334                                 null, ds, out warn, cref, false, null, r).Member as Type;
 335                 }
 336
 337                 private static MemberInfo [] empty_member_infos =
 338                         new MemberInfo [0];
 339
 340                 private static MemberInfo [] FindMethodBase (Type type,
 341                         BindingFlags binding_flags, MethodSignature signature)
 342                 {
 343                         MemberList ml = TypeManager.FindMembers (
 344                                 type,
 345                                 MemberTypes.Constructor | MemberTypes.Method | MemberTypes.Property | MemberTypes.Custom,
 346                                 binding_flags,
 347                                 MethodSignature.method_signature_filter,
 348                                 signature);
 349                         if (ml == null)
 350                                 return empty_member_infos;
 351
 352                         return FilterOverridenMembersOut ((MemberInfo []) ml);
 353                 }
 354
 355                 static bool IsOverride (PropertyInfo deriv_prop, PropertyInfo base_prop)
 356                 {
 357                         if (!MethodGroupExpr.IsAncestralType (base_prop.DeclaringType, deriv_prop.DeclaringType))
 358                                 return false;
 359
 360                         Type [] deriv_pd = TypeManager.GetParameterData (deriv_prop).Types;
 361                         Type [] base_pd = TypeManager.GetParameterData (base_prop).Types;
 362
 363                         if (deriv_pd.Length != base_pd.Length)
 364                                 return false;
 365
 366                         for (int j = 0; j < deriv_pd.Length; ++j) {
 367                                 if (deriv_pd [j] != base_pd [j])
 368                                         return false;
 369                                 Type ct = TypeManager.TypeToCoreType (deriv_pd [j]);
 370                                 Type bt = TypeManager.TypeToCoreType (base_pd [j]);
 371
 372                                 if (ct != bt)
 373                                         return false;
 374                         }
 375
 376                         return true;
 377                 }
 378
 379                 private static MemberInfo [] FilterOverridenMembersOut (
 380                         MemberInfo [] ml)
 381                 {
 382                         if (ml == null)
 383                                 return empty_member_infos;
 384
 385                         var al = new List<MemberInfo> (ml.Length);
 386                         for (int i = 0; i < ml.Length; i++) {
 387                                 MethodBase mx = ml [i] as MethodBase;
 388                                 PropertyInfo px = ml [i] as PropertyInfo;
 389                                 if (mx != null || px != null) {
 390                                         bool overriden = false;
 391                                         for (int j = 0; j < ml.Length; j++) {
 392                                                 if (j == i)
 393                                                         continue;
 394                                                 MethodBase my = ml [j] as MethodBase;
 395                                                 if (mx != null && my != null &&
 396                                                         MethodGroupExpr.IsOverride (my, mx)) {
 397                                                         overriden = true;
 398                                                         break;
 399                                                 }
 400                                                 else if (mx != null)
 401                                                         continue;
 402                                                 PropertyInfo py = ml [j] as PropertyInfo;
 403                                                 if (px != null && py != null &&
 404                                                         IsOverride (py, px)) {
 405                                                         overriden = true;
 406                                                         break;
 407                                                 }
 408                                         }
 409                                         if (overriden)
 410                                                 continue;
 411                                 }
 412                                 al.Add (ml [i]);
 413                         }
 414                         return al.ToArray ();
 415                 }
 416
 417                 struct FoundMember
 418                 {
 419                         public static FoundMember Empty = new FoundMember (true);
 420
 421                         public bool IsEmpty;
 422                         public readonly MemberInfo Member;
 423                         public readonly Type Type;
 424
 425                         public FoundMember (bool regardless_of_this_value_its_empty)
 426                         {
 427                                 IsEmpty = true;
 428                                 Member = null;
 429                                 Type = null;
 430                         }
 431
 432                         public FoundMember (Type found_type, MemberInfo member)
 433                         {
 434                                 IsEmpty = false;
 435                                 Type = found_type;
 436                                 Member = member;
 437                         }
 438                 }
 439
 440                 //
 441                 // Returns a MemberInfo that is referenced in XML documentation
 442                 // (by "see" or "seealso" elements).
 443                 //
 444                 private static FoundMember FindDocumentedMember (MemberCore mc,
 445                         Type type, string member_name, Type [] param_list,
 446                         DeclSpace ds, out int warning_type, string cref,
 447                         bool warn419, string name_for_error, Report r)
 448                 {
 449                         for (; type != null; type = type.DeclaringType) {
 450                                 MemberInfo mi = FindDocumentedMemberNoNest (
 451                                         mc, type, member_name, param_list, ds,
 452                                         out warning_type, cref, warn419,
 453                                         name_for_error, r);
 454                                 if (mi != null)
 455                                         return new FoundMember (type, mi);
 456                         }
 457                         warning_type = 0;
 458                         return FoundMember.Empty;
 459                 }
 460
 461                 private static MemberInfo FindDocumentedMemberNoNest (
 462                         MemberCore mc, Type type, string member_name,
 463                         Type [] param_list, DeclSpace ds, out int warning_type,
 464                         string cref, bool warn419, string name_for_error, Report Report)
 465                 {
 466                         warning_type = 0;
 467                         MemberInfo [] mis;
 468
 469                         if (param_list == null) {
 470                                 // search for fields/events etc.
 471                                 mis = TypeManager.MemberLookup (type, null,
 472                                         type, MemberTypes.All,
 473                                         BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance,
 474                                         member_name, null);
 475                                 mis = FilterOverridenMembersOut (mis);
 476                                 if (mis == null || mis.Length == 0)
 477                                         return null;
 478                                 if (warn419 && IsAmbiguous (mis))
 479                                         Report419 (mc, name_for_error, mis, Report);
 480                                 return mis [0];
 481                         }
 482
 483                         MethodSignature msig = new MethodSignature (member_name, null, param_list);
 484                         mis = FindMethodBase (type,
 485                                 BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance,
 486                                 msig);
 487
 488                         if (warn419 && mis.Length > 0) {
 489                                 if (IsAmbiguous (mis))
 490                                         Report419 (mc, name_for_error, mis, Report);
 491                                 return mis [0];
 492                         }
 493
 494                         // search for operators (whose parameters exactly
 495                         // matches with the list) and possibly report CS1581.
 496                         string oper = null;
 497                         string return_type_name = null;
 498                         if (member_name.StartsWith ("implicit operator ")) {
 499                                 Operator.GetMetadataName (Operator.OpType.Implicit);
 500                                 return_type_name = member_name.Substring (18).Trim (wsChars);
 501                         }
 502                         else if (member_name.StartsWith ("explicit operator ")) {
 503                                 oper = Operator.GetMetadataName (Operator.OpType.Explicit);
 504                                 return_type_name = member_name.Substring (18).Trim (wsChars);
 505                         }
 506                         else if (member_name.StartsWith ("operator ")) {
 507                                 oper = member_name.Substring (9).Trim (wsChars);
 508                                 switch (oper) {
 509                                 // either unary or binary
 510                                 case "+":
 511                                         oper = param_list.Length == 2 ?
 512                                                 Operator.GetMetadataName (Operator.OpType.Addition) :
 513                                                 Operator.GetMetadataName (Operator.OpType.UnaryPlus);
 514                                         break;
 515                                 case "-":
 516                                         oper = param_list.Length == 2 ?
 517                                                 Operator.GetMetadataName (Operator.OpType.Subtraction) :
 518                                                 Operator.GetMetadataName (Operator.OpType.UnaryNegation);
 519                                         break;
 520                                 default:
 521                                         oper = Operator.GetMetadataName (oper);
 522                                         if (oper != null)
 523                                                 break;
 524
 525                                         warning_type = 1584;
 526                                         Report.Warning (1020, 1, mc.Location, "Overloadable {0} operator is expected", param_list.Length == 2 ? "binary" : "unary");
 527                                         Report.Warning (1584, 1, mc.Location, "XML comment on `{0}' has syntactically incorrect cref attribute `{1}'",
 528                                                 mc.GetSignatureForError (), cref);
 529                                         return null;
 530                                 }
 531                         }
 532                         // here we still don't consider return type (to
 533                         // detect CS1581 or CS1002+CS1584).
 534                         msig = new MethodSignature (oper, null, param_list);
 535
 536                         mis = FindMethodBase (type,
 537                                 BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance,
 538                                 msig);
 539                         if (mis.Length == 0)
 540                                 return null; // CS1574
 541                         MemberInfo mi = mis [0];
 542                         Type expected = mi is MethodInfo ?
 543                                 ((MethodInfo) mi).ReturnType :
 544                                 mi is PropertyInfo ?
 545                                 ((PropertyInfo) mi).PropertyType :
 546                                 null;
 547                         if (return_type_name != null) {
 548                                 Type returnType = FindDocumentedType (mc, return_type_name, ds, cref, Report);
 549                                 if (returnType == null || returnType != expected) {
 550                                         warning_type = 1581;
 551                                         Report.Warning (1581, 1, mc.Location, "Invalid return type in XML comment cref attribute `{0}'", cref);
 552                                         return null;
 553                                 }
 554                         }
 555                         return mis [0];
 556                 }
 557
 558                 private static bool IsAmbiguous (MemberInfo [] members)
 559                 {
 560                         if (members.Length < 2)
 561                                 return false;
 562                         if (members.Length > 2)
 563                                 return true;
 564                         if (members [0] is EventInfo && members [1] is FieldInfo)
 565                                 return false;
 566                         if (members [1] is EventInfo && members [0] is FieldInfo)
 567                                 return false;
 568                         return true;
 569                 }
 570
 571                 //
 572                 // Processes "see" or "seealso" elements.
 573                 // Checks cref attribute.
 574                 //
 575                 private static void HandleXrefCommon (MemberCore mc,
 576                         DeclSpace ds, XmlElement xref, Report Report)
 577                 {
 578                         string cref = xref.GetAttribute ("cref").Trim (wsChars);
 579                         // when, XmlReader, "if (cref == null)"
 580                         if (!xref.HasAttribute ("cref"))
 581                                 return;
 582                         if (cref.Length == 0)
 583                                 Report.Warning (1001, 1, mc.Location, "Identifier expected");
 584                                 // ... and continue until CS1584.
 585
 586                         string signature; // "x:" are stripped
 587                         string name; // method invokation "(...)" are removed
 588                         string parameters; // method parameter list
 589
 590                         // When it found '?:' ('T:' 'M:' 'F:' 'P:' 'E:' etc.),
 591                         // MS ignores not only its member kind, but also
 592                         // the entire syntax correctness. Nor it also does
 593                         // type fullname resolution i.e. "T:List(int)" is kept
 594                         // as T:List(int), not
 595                         // T:System.Collections.Generic.List&lt;System.Int32&gt;
 596                         if (cref.Length > 2 && cref [1] == ':')
 597                                 return;
 598                         else
 599                                 signature = cref;
 600
 601                         // Also note that without "T:" any generic type
 602                         // indication fails.
 603
 604                         int parens_pos = signature.IndexOf ('(');
 605                         int brace_pos = parens_pos >= 0 ? -1 :
 606                                 signature.IndexOf ('[');
 607                         if (parens_pos > 0 && signature [signature.Length - 1] == ')') {
 608                                 name = signature.Substring (0, parens_pos).Trim (wsChars);
 609                                 parameters = signature.Substring (parens_pos + 1, signature.Length - parens_pos - 2).Trim (wsChars);
 610                         }
 611                         else if (brace_pos > 0 && signature [signature.Length - 1] == ']') {
 612                                 name = signature.Substring (0, brace_pos).Trim (wsChars);
 613                                 parameters = signature.Substring (brace_pos + 1, signature.Length - brace_pos - 2).Trim (wsChars);
 614                         }
 615                         else {
 616                                 name = signature;
 617                                 parameters = null;
 618                         }
 619                         Normalize (mc, ref name, Report);
 620
 621                         string identifier = GetBodyIdentifierFromName (name);
 622
 623                         // Check if identifier is valid.
 624                         // This check is not necessary to mark as error, but
 625                         // csc specially reports CS1584 for wrong identifiers.
 626                         string [] name_elems = identifier.Split ('.');
 627                         for (int i = 0; i < name_elems.Length; i++) {
 628                                 string nameElem = GetBodyIdentifierFromName (name_elems [i]);
 629                                 if (i > 0)
 630                                         Normalize (mc, ref nameElem, Report);
 631                                 if (!Tokenizer.IsValidIdentifier (nameElem)
 632                                         && nameElem.IndexOf ("operator") < 0) {
 633                                         Report.Warning (1584, 1, mc.Location, "XML comment on `{0}' has syntactically incorrect cref attribute `{1}'",
 634                                                 mc.GetSignatureForError (), cref);
 635                                         xref.SetAttribute ("cref", "!:" + signature);
 636                                         return;
 637                                 }
 638                         }
 639
 640                         // check if parameters are valid
 641                         Type [] parameter_types;
 642                         if (parameters == null)
 643                                 parameter_types = null;
 644                         else if (parameters.Length == 0)
 645                                 parameter_types = Type.EmptyTypes;
 646                         else {
 647                                 string [] param_list = parameters.Split (',');
 648                                 var plist = new List<Type> ();
 649                                 for (int i = 0; i < param_list.Length; i++) {
 650                                         string param_type_name = param_list [i].Trim (wsChars);
 651                                         Normalize (mc, ref param_type_name, Report);
 652                                         Type param_type = FindDocumentedType (mc, param_type_name, ds, cref, Report);
 653                                         if (param_type == null) {
 654                                                 Report.Warning (1580, 1, mc.Location, "Invalid type for parameter `{0}' in XML comment cref attribute `{1}'",
 655                                                         (i + 1).ToString (), cref);
 656                                                 return;
 657                                         }
 658                                         plist.Add (param_type);
 659                                 }
 660                                 parameter_types = plist.ToArray ();
 661                         }
 662
 663                         Type type = FindDocumentedType (mc, name, ds, cref, Report);
 664                         if (type != null
 665                                 // delegate must not be referenced with args
 666                                 && (!TypeManager.IsDelegateType (type)
 667                                 || parameter_types == null)) {
 668                                 string result = GetSignatureForDoc (type)
 669                                         + (brace_pos < 0 ? String.Empty : signature.Substring (brace_pos));
 670                                 xref.SetAttribute ("cref", "T:" + result);
 671                                 return; // a type
 672                         }
 673
 674                         int period = name.LastIndexOf ('.');
 675                         if (period > 0) {
 676                                 string typeName = name.Substring (0, period);
 677                                 string member_name = name.Substring (period + 1);
 678                                 Normalize (mc, ref member_name, Report);
 679                                 type = FindDocumentedType (mc, typeName, ds, cref, Report);
 680                                 int warn_result;
 681                                 if (type != null) {
 682                                         FoundMember fm = FindDocumentedMember (mc, type, member_name, parameter_types, ds, out warn_result, cref, true, name, Report);
 683                                         if (warn_result > 0)
 684                                                 return;
 685                                         if (!fm.IsEmpty) {
 686                                                 MemberInfo mi = fm.Member;
 687                                                 // we cannot use 'type' directly
 688                                                 // to get its name, since mi
 689                                                 // could be from DeclaringType
 690                                                 // for nested types.
 691                                                 xref.SetAttribute ("cref", GetMemberDocHead (mi.MemberType) + GetSignatureForDoc (fm.Type) + "." + member_name + GetParametersFormatted (mi));
 692                                                 return; // a member of a type
 693                                         }
 694                                 }
 695                         }
 696                         else {
 697                                 int warn_result;
 698                                 FoundMember fm = FindDocumentedMember (mc, ds.TypeBuilder, name, parameter_types, ds, out warn_result, cref, true, name, Report);
 699                                 if (warn_result > 0)
 700                                         return;
 701                                 if (!fm.IsEmpty) {
 702                                         MemberInfo mi = fm.Member;
 703                                         // we cannot use 'type' directly
 704                                         // to get its name, since mi
 705                                         // could be from DeclaringType
 706                                         // for nested types.
 707                                         xref.SetAttribute ("cref", GetMemberDocHead (mi.MemberType) + GetSignatureForDoc (fm.Type) + "." + name + GetParametersFormatted (mi));
 708                                         return; // local member name
 709                                 }
 710                         }
 711
 712                         // It still might be part of namespace name.
 713                         Namespace ns = ds.NamespaceEntry.NS.GetNamespace (name, false);
 714                         if (ns != null) {
 715                                 xref.SetAttribute ("cref", "N:" + ns.GetSignatureForError ());
 716                                 return; // a namespace
 717                         }
 718                         if (GlobalRootNamespace.Instance.IsNamespace (name)) {
 719                                 xref.SetAttribute ("cref", "N:" + name);
 720                                 return; // a namespace
 721                         }
 722
 723                         Report.Warning (1574, 1, mc.Location, "XML comment on `{0}' has cref attribute `{1}' that could not be resolved",
 724                                 mc.GetSignatureForError (), cref);
 725
 726                         xref.SetAttribute ("cref", "!:" + name);
 727                 }
 728
 729                 static string GetParametersFormatted (MemberInfo mi)
 730                 {
 731                         MethodBase mb = mi as MethodBase;
 732                         bool is_setter = false;
 733                         PropertyInfo pi = mi as PropertyInfo;
 734                         if (pi != null) {
 735                                 mb = pi.GetGetMethod ();
 736                                 if (mb == null) {
 737                                         is_setter = true;
 738                                         mb = pi.GetSetMethod ();
 739                                 }
 740                         }
 741                         if (mb == null)
 742                                 return String.Empty;
 743
 744                         AParametersCollection parameters = TypeManager.GetParameterData (mb);
 745                         if (parameters == null || parameters.Count == 0)
 746                                 return String.Empty;
 747
 748                         StringBuilder sb = new StringBuilder ();
 749                         sb.Append ('(');
 750                         for (int i = 0; i < parameters.Count; i++) {
 751                                 if (is_setter && i + 1 == parameters.Count)
 752                                         break; // skip "value".
 753                                 if (i > 0)
 754                                         sb.Append (',');
 755                                 Type t = parameters.Types [i];
 756                                 sb.Append (GetSignatureForDoc (t));
 757                         }
 758                         sb.Append (')');
 759                         return sb.ToString ();
 760                 }
 761
 762                 static string GetBodyIdentifierFromName (string name)
 763                 {
 764                         string identifier = name;
 765
 766                         if (name.Length > 0 && name [name.Length - 1] == ']') {
 767                                 string tmp = name.Substring (0, name.Length - 1).Trim (wsChars);
 768                                 int last = tmp.LastIndexOf ('[');
 769                                 if (last > 0)
 770                                         identifier = tmp.Substring (0, last).Trim (wsChars);
 771                         }
 772
 773                         return identifier;
 774                 }
 775
 776                 static void Report419 (MemberCore mc, string member_name, MemberInfo [] mis, Report Report)
 777                 {
 778                         Report.Warning (419, 3, mc.Location,
 779                                 "Ambiguous reference in cref attribute `{0}'. Assuming `{1}' but other overloads including `{2}' have also matched",
 780                                 member_name,
 781                                 TypeManager.GetFullNameSignature (mis [0]),
 782                                 TypeManager.GetFullNameSignature (mis [1]));
 783                 }
 784
 785                 //
 786                 // Get a prefix from member type for XML documentation (used
 787                 // to formalize cref target name).
 788                 //
 789                 static string GetMemberDocHead (MemberTypes type)
 790                 {
 791                         switch (type) {
 792                         case MemberTypes.Constructor:
 793                         case MemberTypes.Method:
 794                                 return "M:";
 795                         case MemberTypes.Event:
 796                                 return "E:";
 797                         case MemberTypes.Field:
 798                                 return "F:";
 799                         case MemberTypes.NestedType:
 800                         case MemberTypes.TypeInfo:
 801                                 return "T:";
 802                         case MemberTypes.Property:
 803                                 return "P:";
 804                         }
 805                         return "!:";
 806                 }
 807
 808                 // MethodCore
 809
 810                 //
 811                 // Returns a string that represents the signature for this
 812                 // member which should be used in XML documentation.
 813                 //
 814                 public static string GetMethodDocCommentName (MemberCore mc, ParametersCompiled parameters, DeclSpace ds)
 815                 {
 816                         IParameterData [] plist = parameters.FixedParameters;
 817                         string paramSpec = String.Empty;
 818                         if (plist != null) {
 819                                 StringBuilder psb = new StringBuilder ();
 820                                 int i = 0;
 821                                 foreach (Parameter p in plist) {
 822                                         psb.Append (psb.Length != 0 ? "," : "(");
 823                                         psb.Append (GetSignatureForDoc (parameters.Types [i++]));
 824                                         if ((p.ModFlags & Parameter.Modifier.ISBYREF) != 0)
 825                                                 psb.Append ('@');
 826                                 }
 827                                 paramSpec = psb.ToString ();
 828                         }
 829
 830                         if (paramSpec.Length > 0)
 831                                 paramSpec += ")";
 832
 833                         string name = mc is Constructor ? "#ctor" : mc.Name;
 834                         if (mc.MemberName.IsGeneric)
 835                                 name += "``" + mc.MemberName.CountTypeArguments;
 836
 837                         string suffix = String.Empty;
 838                         Operator op = mc as Operator;
 839                         if (op != null) {
 840                                 switch (op.OperatorType) {
 841                                 case Operator.OpType.Implicit:
 842                                 case Operator.OpType.Explicit:
 843                                         suffix = "~" + GetSignatureForDoc (op.MethodBuilder.ReturnType);
 844                                         break;
 845                                 }
 846                         }
 847                         return String.Concat (mc.DocCommentHeader, ds.Name, ".", name, paramSpec, suffix);
 848                 }
 849
 850                 static string GetSignatureForDoc (Type type)
 851                 {
 852                         if (TypeManager.IsGenericParameter (type))
 853                                 return (type.DeclaringMethod != null ? "``" : "`") + TypeManager.GenericParameterPosition (type);
 854
 855                         if (TypeManager.IsGenericType (type)) {
 856                                 string g = type.Namespace;
 857                                 if (g != null && g.Length > 0)
 858                                         g += '.';
 859                                 int idx = type.Name.LastIndexOf ('`');
 860                                 g += (idx < 0 ? type.Name : type.Name.Substring (0, idx)) + '{';
 861                                 int argpos = 0;
 862                                 foreach (Type t in type.GetGenericArguments ())
 863                                         g += (argpos++ > 0 ? "," : String.Empty) + GetSignatureForDoc (t);
 864                                 g += '}';
 865                                 return g;
 866                         }
 867
 868                         string name = type.FullName != null ? type.FullName : type.Name;
 869                         return name.Replace ("+", ".").Replace ('&', '@');
 870                 }
 871
 872                 //
 873                 // Raised (and passed an XmlElement that contains the comment)
 874                 // when GenerateDocComment is writing documentation expectedly.
 875                 //
 876                 // FIXME: with a few effort, it could be done with XmlReader,
 877                 // that means removal of DOM use.
 878                 //
 879                 internal static void OnMethodGenerateDocComment (
 880                         MethodCore mc, XmlElement el, Report Report)
 881                 {
 882                         var paramTags = new Dictionary<string, string> ();
 883                         foreach (XmlElement pelem in el.SelectNodes ("param")) {
 884                                 string xname = pelem.GetAttribute ("name");
 885                                 if (xname.Length == 0)
 886                                         continue; // really? but MS looks doing so
 887                                 if (xname != "" && mc.Parameters.GetParameterIndexByName (xname) < 0)
 888                                         Report.Warning (1572, 2, mc.Location, "XML comment on `{0}' has a param tag for `{1}', but there is no parameter by that name",
 889                                                 mc.GetSignatureForError (), xname);
 890                                 else if (paramTags.ContainsKey (xname))
 891                                         Report.Warning (1571, 2, mc.Location, "XML comment on `{0}' has a duplicate param tag for `{1}'",
 892                                                 mc.GetSignatureForError (), xname);
 893                                 paramTags [xname] = xname;
 894                         }
 895                         IParameterData [] plist = mc.Parameters.FixedParameters;
 896                         foreach (Parameter p in plist) {
 897                                 if (paramTags.Count > 0 && !paramTags.ContainsKey (p.Name))
 898                                         Report.Warning (1573, 4, mc.Location, "Parameter `{0}' has no matching param tag in the XML comment for `{1}'",
 899                                                 p.Name, mc.GetSignatureForError ());
 900                         }
 901                 }
 902
 903                 private static void Normalize (MemberCore mc, ref string name, Report Report)
 904                 {
 905                         if (name.Length > 0 && name [0] == '@')
 906                                 name = name.Substring (1);
 907                         else if (name == "this")
 908                                 name = "Item";
 909                         else if (Tokenizer.IsKeyword (name) && !IsTypeName (name))
 910                                 Report.Warning (1041, 1, mc.Location, "Identifier expected. `{0}' is a keyword", name);
 911                 }
 912
 913                 private static bool IsTypeName (string name)
 914                 {
 915                         switch (name) {
 916                         case "bool":
 917                         case "byte":
 918                         case "char":
 919                         case "decimal":
 920                         case "double":
 921                         case "float":
 922                         case "int":
 923                         case "long":
 924                         case "object":
 925                         case "sbyte":
 926                         case "short":
 927                         case "string":
 928                         case "uint":
 929                         case "ulong":
 930                         case "ushort":
 931                         case "void":
 932                                 return true;
 933                         }
 934                         return false;
 935                 }
 936         }
 937
 938         //
 939         // Implements XML documentation generation.
 940         //
 941         public class Documentation
 942         {
 943                 public Documentation (string xml_output_filename)
 944                 {
 945                         docfilename = xml_output_filename;
 946                         XmlDocumentation = new XmlDocument ();
 947                         XmlDocumentation.PreserveWhitespace = false;
 948                 }
 949
 950                 private string docfilename;
 951
 952                 //
 953                 // Used to create element which helps well-formedness checking.
 954                 //
 955                 public XmlDocument XmlDocumentation;
 956
 957                 //
 958                 // The output for XML documentation.
 959                 //
 960                 public XmlWriter XmlCommentOutput;
 961
 962                 //
 963                 // Stores XmlDocuments that are included in XML documentation.
 964                 // Keys are included filenames, values are XmlDocuments.
 965                 //
 966                 public Dictionary<string, XmlDocument> StoredDocuments = new Dictionary<string, XmlDocument> ();
 967
 968                 //
 969                 // Outputs XML documentation comment from tokenized comments.
 970                 //
 971                 public bool OutputDocComment (string asmfilename, Report Report)
 972                 {
 973                         XmlTextWriter w = null;
 974                         try {
 975                                 w = new XmlTextWriter (docfilename, null);
 976                                 w.Indentation = 4;
 977                                 w.Formatting = Formatting.Indented;
 978                                 w.WriteStartDocument ();
 979                                 w.WriteStartElement ("doc");
 980                                 w.WriteStartElement ("assembly");
 981                                 w.WriteStartElement ("name");
 982                                 w.WriteString (Path.ChangeExtension (asmfilename, null));
 983                                 w.WriteEndElement (); // name
 984                                 w.WriteEndElement (); // assembly
 985                                 w.WriteStartElement ("members");
 986                                 XmlCommentOutput = w;
 987                                 GenerateDocComment (Report);
 988                                 w.WriteFullEndElement (); // members
 989                                 w.WriteEndElement ();
 990                                 w.WriteWhitespace (Environment.NewLine);
 991                                 w.WriteEndDocument ();
 992                                 return true;
 993                         } catch (Exception ex) {
 994                                 Report.Error (1569, "Error generating XML documentation file `{0}' (`{1}')", docfilename, ex.Message);
 995                                 return false;
 996                         } finally {
 997                                 if (w != null)
 998                                         w.Close ();
 999                         }
1000                 }
1001
1002                 //
1003                 // Fixes full type name of each documented types/members up.
1004                 //
1005                 public void GenerateDocComment (Report r)
1006                 {
1007                         TypeContainer root = RootContext.ToplevelTypes;
1008
1009                         if (root.Types != null)
1010                                 foreach (TypeContainer tc in root.Types)
1011                                         DocUtil.GenerateTypeDocComment (tc, null, r);
1012
1013                         if (root.Delegates != null)
1014                                 foreach (Delegate d in root.Delegates)
1015                                         DocUtil.GenerateDocComment (d, null, r);
1016                 }
1017         }
1018 }