mcs/mcs/doc.cs

   1 //
   2 // doc.cs: Support for XML documentation comment.
   3 //
   4 // Author:
   5 //      Atsushi Enomoto <atsushi@ximian.com>
   6 //
   7 // Licensed under the terms of the GNU GPL
   8 //
   9 // (C) 2004 Novell, Inc.
  10 //
  11 //
  12
  13 #if ! BOOTSTRAP_WITH_OLDLIB
  14 using System;
  15 using System.Collections;
  16 using System.Collections.Specialized;
  17 using System.IO;
  18 using System.Reflection;
  19 using System.Reflection.Emit;
  20 using System.Runtime.CompilerServices;
  21 using System.Runtime.InteropServices;
  22 using System.Security;
  23 using System.Security.Permissions;
  24 using System.Text;
  25 using System.Xml;
  26
  27 using Mono.CompilerServices.SymbolWriter;
  28
  29 namespace Mono.CSharp {
  30
  31         //
  32         // Support class for XML documentation.
  33         //
  34         public class DocUtil
  35         {
  36                 // TypeContainer
  37
  38                 //
  39                 // Generates xml doc comments (if any), and if required,
  40                 // handle warning report.
  41                 //
  42                 internal static void GenerateTypeDocComment (TypeContainer t,
  43                         DeclSpace ds)
  44                 {
  45                         GenerateDocComment (t, ds);
  46
  47                         if (t.DefaultStaticConstructor != null)
  48                                 t.DefaultStaticConstructor.GenerateDocComment (t);
  49
  50                         if (t.InstanceConstructors != null)
  51                                 foreach (Constructor c in t.InstanceConstructors)
  52                                         c.GenerateDocComment (t);
  53
  54                         if (t.Types != null)
  55                                 foreach (TypeContainer tc in t.Types)
  56                                         tc.GenerateDocComment (t);
  57
  58                         if (t.Parts != null) {
  59                                 IDictionary comments = RootContext.Documentation.PartialComments;
  60                                 foreach (ClassPart cp in t.Parts) {
  61                                         if (cp.DocComment == null)
  62                                                 continue;
  63                                         comments [cp] = cp;
  64                                 }
  65                         }
  66
  67                         if (t.Enums != null)
  68                                 foreach (Enum en in t.Enums)
  69                                         en.GenerateDocComment (t);
  70
  71                         if (t.Constants != null)
  72                                 foreach (Const c in t.Constants)
  73                                         c.GenerateDocComment (t);
  74
  75                         if (t.Fields != null)
  76                                 foreach (Field f in t.Fields)
  77                                         f.GenerateDocComment (t);
  78
  79                         if (t.Events != null)
  80                                 foreach (Event e in t.Events)
  81                                         e.GenerateDocComment (t);
  82
  83                         if (t.Indexers != null)
  84                                 foreach (Indexer ix in t.Indexers)
  85                                         ix.GenerateDocComment (t);
  86
  87                         if (t.Properties != null)
  88                                 foreach (Property p in t.Properties)
  89                                         p.GenerateDocComment (t);
  90
  91                         if (t.Methods != null)
  92                                 foreach (Method m in t.Methods)
  93                                         m.GenerateDocComment (t);
  94
  95                         if (t.Operators != null)
  96                                 foreach (Operator o in t.Operators)
  97                                         o.GenerateDocComment (t);
  98                 }
  99
 100                 // MemberCore
 101                 private static readonly string lineHead =
 102                         Environment.NewLine + "            ";
 103
 104                 private static XmlNode GetDocCommentNode (MemberCore mc,
 105                         string name)
 106                 {
 107                         // FIXME: It could be even optimizable as not
 108                         // to use XmlDocument. But anyways the nodes
 109                         // are not kept in memory.
 110                         XmlDocument doc = RootContext.Documentation.XmlDocumentation;
 111                         try {
 112                                 XmlElement el = doc.CreateElement ("member");
 113                                 el.SetAttribute ("name", name);
 114                                 string normalized = mc.DocComment;
 115                                 el.InnerXml = normalized;
 116                                 // csc keeps lines as written in the sources
 117                                 // and inserts formatting indentation (which
 118                                 // is different from XmlTextWriter.Formatting
 119                                 // one), but when a start tag contains an
 120                                 // endline, it joins the next line. We don't
 121                                 // have to follow such a hacky behavior.
 122                                 string [] split =
 123                                         normalized.Split ('\n');
 124                                 int j = 0;
 125                                 for (int i = 0; i < split.Length; i++) {
 126                                         string s = split [i].TrimEnd ();
 127                                         if (s.Length > 0)
 128                                                 split [j++] = s;
 129                                 }
 130                                 el.InnerXml = lineHead + String.Join (
 131                                         lineHead, split, 0, j);
 132                                 return el;
 133                         } catch (XmlException ex) {
 134                                 Report.Warning (1570, 1, mc.Location, "XML comment on '{0}' has non-well-formed XML ({1}).", name, ex.Message);
 135                                 XmlComment com = doc.CreateComment (String.Format ("FIXME: Invalid documentation markup was found for member {0}", name));
 136                                 return com;
 137                         }
 138                 }
 139
 140                 //
 141                 // Generates xml doc comments (if any), and if required,
 142                 // handle warning report.
 143                 //
 144                 internal static void GenerateDocComment (MemberCore mc,
 145                         DeclSpace ds)
 146                 {
 147                         if (mc.DocComment != null) {
 148                                 string name = mc.GetDocCommentName (ds);
 149
 150                                 XmlNode n = GetDocCommentNode (mc, name);
 151
 152                                 XmlElement el = n as XmlElement;
 153                                 if (el != null) {
 154                                         mc.OnGenerateDocComment (ds, el);
 155
 156                                         // FIXME: it could be done with XmlReader
 157                                         foreach (XmlElement inc in n.SelectNodes (".//include"))
 158                                                 HandleInclude (mc, inc);
 159
 160                                         // FIXME: it could be done with XmlReader
 161                                         DeclSpace dsTarget = mc as DeclSpace;
 162                                         if (dsTarget == null)
 163                                                 dsTarget = ds;
 164
 165                                         foreach (XmlElement see in n.SelectNodes (".//see"))
 166                                                 HandleSee (mc, dsTarget, see);
 167                                         foreach (XmlElement seealso in n.SelectNodes (".//seealso"))
 168                                                 HandleSeeAlso (mc, dsTarget, seealso);
 169                                         foreach (XmlElement see in n.SelectNodes (".//exception"))
 170                                                 HandleException (mc, dsTarget, see);
 171                                 }
 172
 173                                 n.WriteTo (RootContext.Documentation.XmlCommentOutput);
 174                         }
 175                         else if (mc.IsExposedFromAssembly (ds) &&
 176                                 // There are no warnings when the container also
 177                                 // misses documentations.
 178                                 (ds == null || ds.DocComment != null))
 179                         {
 180                                 Report.Warning (1591, 4, mc.Location,
 181                                         "Missing XML comment for publicly visible type or member '{0}'", mc.GetSignatureForError ());
 182                         }
 183                 }
 184
 185                 //
 186                 // Processes "include" element. Check included file and
 187                 // embed the document content inside this documentation node.
 188                 //
 189                 private static void HandleInclude (MemberCore mc, XmlElement el)
 190                 {
 191                         string file = el.GetAttribute ("file");
 192                         string path = el.GetAttribute ("path");
 193                         if (file == "") {
 194                                 Report.Warning (1590, 1, mc.Location, "Invalid XML 'include' element; Missing 'file' attribute.");
 195                                 el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" Include tag is invalid "), el);
 196                         }
 197                         else if (path == "") {
 198                                 Report.Warning (1590, 1, mc.Location, "Invalid XML 'include' element; Missing 'path' attribute.");
 199                                 el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" Include tag is invalid "), el);
 200                         }
 201                         else {
 202                                 XmlDocument doc = RootContext.Documentation.StoredDocuments [file] as XmlDocument;
 203                                 if (doc == null) {
 204                                         try {
 205                                                 doc = new XmlDocument ();
 206                                                 doc.Load (file);
 207                                                 RootContext.Documentation.StoredDocuments.Add (file, doc);
 208                                         } catch (Exception) {
 209                                                 el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (String.Format (" Badly formed XML in at comment file '{0}': cannot be included ", file)), el);
 210                                                 Report.Warning (1592, 1, mc.Location, "Badly formed XML in included comments file -- '{0}'", file);
 211                                         }
 212                                 }
 213                                 bool keepIncludeNode = false;
 214                                 if (doc != null) {
 215                                         try {
 216                                                 XmlNodeList nl = doc.SelectNodes (path);
 217                                                 if (nl.Count == 0) {
 218                                                         el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" No matching elements were found for the include tag embedded here. "), el);
 219
 220                                                         keepIncludeNode = true;
 221                                                 }
 222                                                 foreach (XmlNode n in nl)
 223                                                         el.ParentNode.InsertBefore (el.OwnerDocument.ImportNode (n, true), el);
 224                                         } catch (Exception ex) {
 225                                                 el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" Failed to insert some or all of included XML "), el);
 226                                                 Report.Warning (1589, 1, mc.Location, "Unable to include XML fragment '{0}' of file {1} -- {2}.", path, file, ex.Message);
 227                                         }
 228                                 }
 229                                 if (!keepIncludeNode)
 230                                         el.ParentNode.RemoveChild (el);
 231                         }
 232                 }
 233
 234                 //
 235                 // Handles <see> elements.
 236                 //
 237                 private static void HandleSee (MemberCore mc,
 238                         DeclSpace ds, XmlElement see)
 239                 {
 240                         HandleXrefCommon (mc, ds, see);
 241                 }
 242
 243                 //
 244                 // Handles <seealso> elements.
 245                 //
 246                 private static void HandleSeeAlso (MemberCore mc,
 247                         DeclSpace ds, XmlElement seealso)
 248                 {
 249                         HandleXrefCommon (mc, ds, seealso);
 250                 }
 251
 252                 //
 253                 // Handles <exception> elements.
 254                 //
 255                 private static void HandleException (MemberCore mc,
 256                         DeclSpace ds, XmlElement seealso)
 257                 {
 258                         HandleXrefCommon (mc, ds, seealso);
 259                 }
 260
 261                 static readonly char [] wsChars =
 262                         new char [] {' ', '\t', '\n', '\r'};
 263
 264                 //
 265                 // returns a full runtime type name from a name which might
 266                 // be C# specific type name.
 267                 //
 268                 private static Type FindDocumentedType (MemberCore mc,
 269                         string name, DeclSpace ds, bool allowAlias)
 270                 {
 271                         bool isArray = false;
 272                         string identifier = name;
 273                         if (name [name.Length - 1] == ']') {
 274                                 string tmp = name.Substring (0, name.Length - 1).Trim (wsChars);
 275                                 if (tmp [tmp.Length - 1] == '[') {
 276                                         identifier = tmp.Substring (0, tmp.Length - 1).Trim (wsChars);
 277                                         isArray = true;
 278                                 }
 279                         }
 280                         Type t = FindDocumentedTypeNonArray (mc, identifier,
 281                                 ds, allowAlias);
 282                         if (t != null && isArray)
 283                                 t = Array.CreateInstance (t, 0).GetType ();
 284                         return t;
 285                 }
 286
 287                 private static Type FindDocumentedTypeNonArray (MemberCore mc,
 288                         string identifier, DeclSpace ds, bool allowAlias)
 289                 {
 290                         switch (identifier) {
 291                         case "int":
 292                                 return typeof (int);
 293                         case "uint":
 294                                 return typeof (uint);
 295                         case "short":
 296                                 return typeof (short);
 297                         case "ushort":
 298                                 return typeof (ushort);
 299                         case "long":
 300                                 return typeof (long);
 301                         case "ulong":
 302                                 return typeof (ulong);
 303                         case "float":
 304                                 return typeof (float);
 305                         case "double":
 306                                 return typeof (double);
 307                         case "char":
 308                                 return typeof (char);
 309                         case "decimal":
 310                                 return typeof (decimal);
 311                         case "byte":
 312                                 return typeof (byte);
 313                         case "sbyte":
 314                                 return typeof (sbyte);
 315                         case "object":
 316                                 return typeof (object);
 317                         case "bool":
 318                                 return typeof (bool);
 319                         case "string":
 320                                 return typeof (string);
 321                         case "void":
 322                                 return typeof (void);
 323                         }
 324                         if (allowAlias) {
 325                                 IAlias alias = ds.LookupAlias (identifier);
 326                                 if (alias != null)
 327                                         identifier = alias.Name;
 328                         }
 329                         Type t = ds.FindType (mc.Location, identifier);
 330                         if (t == null)
 331                                 t = TypeManager.LookupTypeDirect (identifier);
 332                         return t;
 333                 }
 334
 335                 //
 336                 // Returns a MemberInfo that is referenced in XML documentation
 337                 // (by "see" or "seealso" elements).
 338                 //
 339                 private static MemberInfo FindDocumentedMember (MemberCore mc,
 340                         Type type, string memberName, Type [] paramList,
 341                         DeclSpace ds, out int warningType, string cref)
 342                 {
 343                         warningType = 0;
 344                         MethodSignature msig = new MethodSignature (memberName, null, paramList);
 345                         MemberInfo [] mis = type.FindMembers (
 346                                 MemberTypes.All,
 347                                 BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance,
 348                                 MethodSignature.method_signature_filter,
 349                                 msig);
 350                         if (mis.Length > 0)
 351                                 return mis [0];
 352
 353                         if (paramList.Length == 0) {
 354                                 // search for fields/events etc.
 355                                 mis = type.FindMembers (
 356                                         MemberTypes.All,
 357                                         BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance,
 358                                         Type.FilterName,
 359                                         memberName);
 360                                 return (mis.Length > 0) ? mis [0] : null;
 361                         }
 362
 363                         // search for operators (whose parameters exactly
 364                         // matches with the list) and possibly report CS1581.
 365                         string oper = null;
 366                         string returnTypeName = null;
 367                         if (memberName.StartsWith ("implicit operator ")) {
 368                                 oper = "op_Implicit";
 369                                 returnTypeName = memberName.Substring (18).Trim (wsChars);
 370                         }
 371                         else if (memberName.StartsWith ("explicit operator ")) {
 372                                 oper = "op_Explicit";
 373                                 returnTypeName = memberName.Substring (18).Trim (wsChars);
 374                         }
 375                         else if (memberName.StartsWith ("operator ")) {
 376                                 oper = memberName.Substring (9).Trim (wsChars);
 377                                 switch (oper) {
 378                                 // either unary or binary
 379                                 case "+":
 380                                         oper = paramList.Length == 2 ?
 381                                                 Binary.oper_names [(int) Binary.Operator.Addition] :
 382                                                 Unary.oper_names [(int) Unary.Operator.UnaryPlus];
 383                                         break;
 384                                 case "-":
 385                                         oper = paramList.Length == 2 ?
 386                                                 Binary.oper_names [(int) Binary.Operator.Subtraction] :
 387                                                 Unary.oper_names [(int) Unary.Operator.UnaryNegation];
 388                                         break;
 389                                 // unary
 390                                 case "!":
 391                                         oper = Unary.oper_names [(int) Unary.Operator.LogicalNot]; break;
 392                                 case "~":
 393                                         oper = Unary.oper_names [(int) Unary.Operator.OnesComplement]; break;
 394
 395                                 case "++":
 396                                         oper = "op_Increment"; break;
 397                                 case "--":
 398                                         oper = "op_Decrement"; break;
 399                                 case "true":
 400                                         oper = "op_True"; break;
 401                                 case "false":
 402                                         oper = "op_False"; break;
 403                                 // binary
 404                                 case "*":
 405                                         oper = Binary.oper_names [(int) Binary.Operator.Multiply]; break;
 406                                 case "/":
 407                                         oper = Binary.oper_names [(int) Binary.Operator.Division]; break;
 408                                 case "%":
 409                                         oper = Binary.oper_names [(int) Binary.Operator.Modulus]; break;
 410                                 case "&":
 411                                         oper = Binary.oper_names [(int) Binary.Operator.BitwiseAnd]; break;
 412                                 case "|":
 413                                         oper = Binary.oper_names [(int) Binary.Operator.BitwiseOr]; break;
 414                                 case "^":
 415                                         oper = Binary.oper_names [(int) Binary.Operator.ExclusiveOr]; break;
 416                                 case "<<":
 417                                         oper = Binary.oper_names [(int) Binary.Operator.LeftShift]; break;
 418                                 case ">>":
 419                                         oper = Binary.oper_names [(int) Binary.Operator.RightShift]; break;
 420                                 case "==":
 421                                         oper = Binary.oper_names [(int) Binary.Operator.Equality]; break;
 422                                 case "!=":
 423                                         oper = Binary.oper_names [(int) Binary.Operator.Inequality]; break;
 424                                 case "<":
 425                                         oper = Binary.oper_names [(int) Binary.Operator.LessThan]; break;
 426                                 case ">":
 427                                         oper = Binary.oper_names [(int) Binary.Operator.GreaterThan]; break;
 428                                 case "<=":
 429                                         oper = Binary.oper_names [(int) Binary.Operator.LessThanOrEqual]; break;
 430                                 case ">=":
 431                                         oper = Binary.oper_names [(int) Binary.Operator.GreaterThanOrEqual]; break;
 432                                 default:
 433                                         warningType = 1584;
 434                                         Report.Warning (1020, 1, mc.Location, "Overloadable {0} operator is expected", paramList.Length == 2 ? "binary" : "unary");
 435                                         Report.Warning (1584, 1, mc.Location, "XML comment on '{0}' has syntactically incorrect attribute '{1}'", mc.GetSignatureForError (), cref);
 436                                         return null;
 437                                 }
 438                         }
 439                         // here we still does not consider return type (to
 440                         // detect CS1581 or CS1002+CS1584).
 441                         msig = new MethodSignature (oper, null, paramList);
 442                         mis = type.FindMembers (
 443                                 MemberTypes.Method,
 444                                 BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static,
 445                                 MethodSignature.method_signature_filter,
 446                                 msig);
 447                         if (mis.Length == 0)
 448                                 return null; // CS1574
 449                         MemberInfo mi = mis [0];
 450                         Type expected = mi is MethodInfo ?
 451                                 ((MethodInfo) mi).ReturnType :
 452                                 mi is PropertyInfo ?
 453                                 ((PropertyInfo) mi).PropertyType :
 454                                 null;
 455                         if (returnTypeName != null) {
 456                                 Type returnType = FindDocumentedType (mc, returnTypeName, ds, true);
 457                                 if (returnType == null || returnType != expected) {
 458                                         warningType = 1581;
 459                                         Report.Warning (1581, 1, mc.Location, "Invalid return type in XML comment cref attribute '{0}'", cref);
 460                                         return null;
 461                                 }
 462                         }
 463                         return mis [0];
 464                 }
 465
 466                 private static Type [] emptyParamList = new Type [0];
 467
 468                 //
 469                 // Processes "see" or "seealso" elements.
 470                 // Checks cref attribute.
 471                 //
 472                 private static void HandleXrefCommon (MemberCore mc,
 473                         DeclSpace ds, XmlElement xref)
 474                 {
 475                         string cref = xref.GetAttribute ("cref").Trim (wsChars);
 476                         // when, XmlReader, "if (cref == null)"
 477                         if (!xref.HasAttribute ("cref"))
 478                                 return;
 479                         if (cref.Length == 0)
 480                                 Report.Warning (1001, 1, mc.Location, "Identifier expected");
 481                                 // ... and continue until CS1584.
 482
 483                         string signature; // "x:" are stripped
 484                         string name; // method invokation "(...)" are removed
 485                         string parameters; // method parameter list
 486
 487                         // strip 'T:' 'M:' 'F:' 'P:' 'E:' etc.
 488                         // Here, MS ignores its member kind. No idea why.
 489                         if (cref.Length > 2 && cref [1] == ':')
 490                                 signature = cref.Substring (2).Trim (wsChars);
 491                         else
 492                                 signature = cref;
 493
 494                         int parensPos = signature.IndexOf ('(');
 495                         if (parensPos > 0 && signature [signature.Length - 1] == ')') {
 496                                 name = signature.Substring (0, parensPos).Trim (wsChars);
 497                                 parameters = signature.Substring (parensPos + 1, signature.Length - parensPos - 2);
 498                         }
 499                         else {
 500                                 name = signature;
 501                                 parameters = String.Empty;
 502                         }
 503
 504                         string identifier = name;
 505
 506                         if (name.Length > 0 && name [name.Length - 1] == ']') {
 507                                 string tmp = name.Substring (0, name.Length - 1).Trim (wsChars);
 508                                 if (tmp [tmp.Length - 1] == '[')
 509                                         identifier = tmp.Substring (0, tmp.Length - 1).Trim (wsChars);
 510                         }
 511
 512                         // Check if identifier is valid.
 513                         // This check is not necessary to mark as error, but
 514                         // csc specially reports CS1584 for wrong identifiers.
 515                         foreach (string nameElem in identifier.Split ('.')) {
 516                                 if (!Tokenizer.IsValidIdentifier (nameElem)
 517                                         && nameElem.IndexOf ("operator") < 0) {
 518                                         if (nameElem.EndsWith ("[]") &&
 519                                                 Tokenizer.IsValidIdentifier (
 520                                                 nameElem.Substring (
 521                                                 0, nameElem.Length - 2)))
 522                                                 continue;
 523
 524                                         Report.Warning (1584, 1, mc.Location, "XML comment on '{0}' has syntactically incorrect attribute '{1}'", mc.GetSignatureForError (), cref);
 525                                         xref.SetAttribute ("cref", "!:" + signature);
 526                                         return;
 527                                 }
 528                         }
 529
 530                         // check if parameters are valid
 531                         Type [] parameterTypes = emptyParamList;
 532                         if (parameters.Length > 0) {
 533                                 string [] paramList = parameters.Split (',');
 534                                 ArrayList plist = new ArrayList ();
 535                                 for (int i = 0; i < paramList.Length; i++) {
 536                                         string paramTypeName = paramList [i].Trim (wsChars);
 537                                         Type paramType = FindDocumentedType (mc, paramTypeName, ds, true);
 538                                         if (paramType == null) {
 539                                                 Report.Warning (1580, 1, mc.Location, "Invalid type for parameter '{0}' in XML comment cref attribute '{1}'", i + 1, cref);
 540                                                 return;
 541                                         }
 542                                         plist.Add (paramType);
 543                                 }
 544                                 parameterTypes = plist.ToArray (typeof (Type)) as Type [];
 545                                 StringBuilder sb = new StringBuilder ();
 546                                 sb.Append ('(');
 547                                 for (int i = 0; i < parameterTypes.Length; i++) {
 548                                         Type t = parameterTypes [i];
 549                                         if (sb.Length > 1)
 550                                                 sb.Append (',');
 551                                         sb.Append (t.FullName.Replace ('+', '.'));
 552                                 }
 553                                 sb.Append (')');
 554                                 parameters = sb.ToString ();
 555                         }
 556
 557                         Type type = FindDocumentedType (mc, name, ds, true);
 558                         if (type != null) {
 559                                 xref.SetAttribute ("cref", "T:" + type.FullName.Replace ("+", "."));
 560                                 return; // a type
 561                         }
 562
 563                         // don't use identifier here. System[] is not alloed.
 564                         if (Namespace.IsNamespace (name)) {
 565                                 xref.SetAttribute ("cref", "N:" + name);
 566                                 return; // a namespace
 567                         }
 568
 569                         int period = name.LastIndexOf ('.');
 570                         if (period > 0) {
 571                                 string typeName = name.Substring (0, period);
 572                                 string memberName = name.Substring (period + 1);
 573                                 type = FindDocumentedType (mc, typeName, ds, false);
 574                                 int warnResult;
 575                                 if (type != null) {
 576                                         MemberInfo mi = FindDocumentedMember (mc, type, memberName, parameterTypes, ds, out warnResult, cref);
 577                                         if (warnResult > 0)
 578                                                 return;
 579                                         if (mi != null) {
 580                                                 xref.SetAttribute ("cref", GetMemberDocHead (mi.MemberType) + type.FullName.Replace ("+", ".") + "." + memberName + parameters);
 581                                                 return; // a member of a type
 582                                         }
 583                                 }
 584                         }
 585                         else {
 586                                 int warnResult;
 587                                 MemberInfo mi = FindDocumentedMember (mc, ds.TypeBuilder, name, parameterTypes, ds, out warnResult, cref);
 588                                 if (warnResult > 0)
 589                                         return;
 590                                 if (mi != null) {
 591                                         xref.SetAttribute ("cref", GetMemberDocHead (mi.MemberType) + ds.TypeBuilder.FullName.Replace ("+", ".") + "." + name);
 592                                         return; // local member name
 593                                 }
 594                         }
 595
 596                         Report.Warning (1574, 1, mc.Location, "XML comment on '{0}' has cref attribute '{1}' that could not be resolved in '{2}'.", mc.GetSignatureForError (), cref, ds.GetSignatureForError ());
 597
 598                         xref.SetAttribute ("cref", "!:" + name);
 599                 }
 600
 601                 //
 602                 // Get a prefix from member type for XML documentation (used
 603                 // to formalize cref target name).
 604                 //
 605                 static string GetMemberDocHead (MemberTypes type)
 606                 {
 607                         switch (type) {
 608                         case MemberTypes.Constructor:
 609                         case MemberTypes.Method:
 610                                 return "M:";
 611                         case MemberTypes.Event:
 612                                 return "E:";
 613                         case MemberTypes.Field:
 614                                 return "F:";
 615                         case MemberTypes.NestedType:
 616                         case MemberTypes.TypeInfo:
 617                                 return "T:";
 618                         case MemberTypes.Property:
 619                                 return "P:";
 620                         }
 621                         return "!:";
 622                 }
 623
 624                 // MethodCore
 625
 626                 //
 627                 // Returns a string that represents the signature for this
 628                 // member which should be used in XML documentation.
 629                 //
 630                 public static string GetMethodDocCommentName (MethodCore mc, DeclSpace ds)
 631                 {
 632                         Parameter [] plist = mc.Parameters.FixedParameters;
 633                         Parameter parr = mc.Parameters.ArrayParameter;
 634                         string paramSpec = String.Empty;
 635                         if (plist != null) {
 636                                 StringBuilder psb = new StringBuilder ();
 637                                 foreach (Parameter p in plist) {
 638                                         psb.Append (psb.Length != 0 ? "," : "(");
 639                                         psb.Append (p.ParameterType.FullName.Replace ("+", "."));
 640                                 }
 641                                 paramSpec = psb.ToString ();
 642                         }
 643                         if (parr != null)
 644                                 paramSpec += String.Concat (
 645                                         paramSpec == String.Empty ? "(" : ",",
 646                                         parr.ParameterType.FullName.Replace ("+", "."));
 647
 648                         if (paramSpec.Length > 0)
 649                                 paramSpec += ")";
 650
 651                         string name = mc is Constructor ? "#ctor" : mc.Name;
 652                         string suffix = String.Empty;
 653                         Operator op = mc as Operator;
 654                         if (op != null) {
 655                                 switch (op.OperatorType) {
 656                                 case Operator.OpType.Implicit:
 657                                 case Operator.OpType.Explicit:
 658                                         suffix = "~" + op.OperatorMethodBuilder.ReturnType.FullName.Replace ('+', '.');
 659                                         break;
 660                                 }
 661                         }
 662                         return String.Concat (mc.DocCommentHeader, ds.Name, ".", name, paramSpec, suffix);
 663                 }
 664
 665                 //
 666                 // Raised (and passed an XmlElement that contains the comment)
 667                 // when GenerateDocComment is writing documentation expectedly.
 668                 //
 669                 // FIXME: with a few effort, it could be done with XmlReader,
 670                 // that means removal of DOM use.
 671                 //
 672                 internal static void OnMethodGenerateDocComment (
 673                         MethodCore mc, DeclSpace ds, XmlElement el)
 674                 {
 675                         Hashtable paramTags = new Hashtable ();
 676                         foreach (XmlElement pelem in el.SelectNodes ("param")) {
 677                                 int i;
 678                                 string xname = pelem.GetAttribute ("name");
 679                                 if (xname == "")
 680                                         continue; // really? but MS looks doing so
 681                                 if (xname != "" && mc.Parameters.GetParameterByName (xname, out i) == null)
 682                                         Report.Warning (1572, 2, mc.Location, "XML comment on '{0}' has a 'param' tag for '{1}', but there is no such parameter.", mc.Name, xname);
 683                                 else if (paramTags [xname] != null)
 684                                         Report.Warning (1571, 2, mc.Location, "XML comment on '{0}' has a duplicate param tag for '{1}'", mc.Name, xname);
 685                                 paramTags [xname] = xname;
 686                         }
 687                         Parameter [] plist = mc.Parameters.FixedParameters;
 688                         if (plist != null) {
 689                                 foreach (Parameter p in plist) {
 690                                         if (paramTags.Count > 0 && paramTags [p.Name] == null)
 691                                                 Report.Warning (1573, 4, mc.Location, "Parameter '{0}' has no matching param tag in the XML comment for '{1}' (but other parameters do)", mc.Name, p.Name);
 692                                 }
 693                         }
 694                 }
 695
 696                 // Enum
 697                 public static void GenerateEnumDocComment (Enum e, DeclSpace ds)
 698                 {
 699                         GenerateDocComment (e, ds);
 700                         foreach (string name in e.ordered_enums) {
 701                                 MemberCore mc = e.GetDefinition (name);
 702                                 GenerateDocComment (mc, e);
 703                         }
 704                 }
 705         }
 706
 707         //
 708         // Implements XML documentation generation.
 709         //
 710         public class Documentation
 711         {
 712                 public Documentation (string xml_output_filename)
 713                 {
 714                         docfilename = xml_output_filename;
 715                         XmlDocumentation = new XmlDocument ();
 716                         XmlDocumentation.PreserveWhitespace = false;
 717                 }
 718
 719                 private string docfilename;
 720
 721                 //
 722                 // Used to create element which helps well-formedness checking.
 723                 //
 724                 public XmlDocument XmlDocumentation;
 725
 726                 //
 727                 // The output for XML documentation.
 728                 //
 729                 public XmlWriter XmlCommentOutput;
 730
 731                 //
 732                 // Stores XmlDocuments that are included in XML documentation.
 733                 // Keys are included filenames, values are XmlDocuments.
 734                 //
 735                 public Hashtable StoredDocuments = new Hashtable ();
 736
 737                 //
 738                 // Stores comments on partial types (should handle uniquely).
 739                 // Keys are PartialContainers, values are comment strings
 740                 // (didn't use StringBuilder; usually we have just 2 or more).
 741                 //
 742                 public IDictionary PartialComments = new ListDictionary ();
 743
 744                 //
 745                 // Outputs XML documentation comment from tokenized comments.
 746                 //
 747                 public bool OutputDocComment (string asmfilename)
 748                 {
 749                         XmlTextWriter w = null;
 750                         try {
 751                                 w = new XmlTextWriter (docfilename, null);
 752                                 w.Indentation = 4;
 753                                 w.Formatting = Formatting.Indented;
 754                                 w.WriteStartDocument ();
 755                                 w.WriteStartElement ("doc");
 756                                 w.WriteStartElement ("assembly");
 757                                 w.WriteStartElement ("name");
 758                                 w.WriteString (Path.ChangeExtension (asmfilename, null));
 759                                 w.WriteEndElement (); // name
 760                                 w.WriteEndElement (); // assembly
 761                                 w.WriteStartElement ("members");
 762                                 XmlCommentOutput = w;
 763                                 GenerateDocComment ();
 764                                 w.WriteFullEndElement (); // members
 765                                 w.WriteEndElement ();
 766                                 w.WriteWhitespace (Environment.NewLine);
 767                                 w.WriteEndDocument ();
 768                                 return true;
 769                         } catch (Exception ex) {
 770                                 Report.Error (1569, "Error generating XML documentation file '{0}' ('{1}')", docfilename, ex.Message);
 771                                 return false;
 772                         } finally {
 773                                 if (w != null)
 774                                         w.Close ();
 775                         }
 776                 }
 777
 778                 //
 779                 // Fixes full type name of each documented types/members up.
 780                 //
 781                 public void GenerateDocComment ()
 782                 {
 783                         TypeContainer root = RootContext.Tree.Types;
 784                         if (root.Interfaces != null)
 785                                 foreach (Interface i in root.Interfaces)
 786                                         DocUtil.GenerateTypeDocComment (i, null);
 787
 788                         if (root.Types != null)
 789                                 foreach (TypeContainer tc in root.Types)
 790                                         DocUtil.GenerateTypeDocComment (tc, null);
 791
 792                         if (root.Parts != null) {
 793                                 IDictionary comments = PartialComments;
 794                                 foreach (ClassPart cp in root.Parts) {
 795                                         if (cp.DocComment == null)
 796                                                 continue;
 797                                         comments [cp] = cp;
 798                                 }
 799                         }
 800
 801                         if (root.Delegates != null)
 802                                 foreach (Delegate d in root.Delegates)
 803                                         DocUtil.GenerateDocComment (d, null);
 804
 805                         if (root.Enums != null)
 806                                 foreach (Enum e in root.Enums)
 807                                         DocUtil.GenerateEnumDocComment (e, null);
 808
 809                         IDictionary table = new ListDictionary ();
 810                         foreach (ClassPart cp in PartialComments.Keys) {
 811                                 table [cp.PartialContainer] += cp.DocComment;
 812                         }
 813                         foreach (PartialContainer pc in table.Keys) {
 814                                 pc.DocComment = table [pc] as string;
 815                                 DocUtil.GenerateDocComment (pc, null);
 816                         }
 817                 }
 818         }
 819 }
 820
 821 #endif