2 // doc.cs: Support for XML documentation comment.
5 // Atsushi Enomoto <atsushi@ximian.com>
7 // Licensed under the terms of the GNU GPL
9 // (C) 2004 Novell, Inc.
13 #if ! BOOTSTRAP_WITH_OLDLIB
15 using System.Collections;
16 using System.Collections.Specialized;
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;
27 using Mono.CompilerServices.SymbolWriter;
29 namespace Mono.CSharp {
32 // Support class for XML documentation.
39 // Generates xml doc comments (if any), and if required,
40 // handle warning report.
42 internal static void GenerateTypeDocComment (TypeContainer t,
45 GenerateDocComment (t, ds);
47 if (t.DefaultStaticConstructor != null)
48 t.DefaultStaticConstructor.GenerateDocComment (t);
50 if (t.InstanceConstructors != null)
51 foreach (Constructor c in t.InstanceConstructors)
52 c.GenerateDocComment (t);
55 foreach (TypeContainer tc in t.Types)
56 tc.GenerateDocComment (t);
58 if (t.Parts != null) {
59 IDictionary comments = RootContext.Documentation.PartialComments;
60 foreach (ClassPart cp in t.Parts) {
61 if (cp.DocComment == null)
68 foreach (Enum en in t.Enums)
69 en.GenerateDocComment (t);
71 if (t.Constants != null)
72 foreach (Const c in t.Constants)
73 c.GenerateDocComment (t);
76 foreach (FieldBase f in t.Fields)
77 f.GenerateDocComment (t);
80 foreach (Event e in t.Events)
81 e.GenerateDocComment (t);
83 if (t.Indexers != null)
84 foreach (Indexer ix in t.Indexers)
85 ix.GenerateDocComment (t);
87 if (t.Properties != null)
88 foreach (Property p in t.Properties)
89 p.GenerateDocComment (t);
91 if (t.Methods != null)
92 foreach (Method m in t.Methods)
93 m.GenerateDocComment (t);
95 if (t.Operators != null)
96 foreach (Operator o in t.Operators)
97 o.GenerateDocComment (t);
101 private static readonly string lineHead =
102 Environment.NewLine + " ";
104 private static XmlNode GetDocCommentNode (MemberCore mc,
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;
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.
123 normalized.Split ('\n');
125 for (int i = 0; i < split.Length; i++) {
126 string s = split [i].TrimEnd ();
130 el.InnerXml = lineHead + String.Join (
131 lineHead, split, 0, j);
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));
141 // Generates xml doc comments (if any), and if required,
142 // handle warning report.
144 internal static void GenerateDocComment (MemberCore mc,
147 if (mc.DocComment != null) {
148 string name = mc.GetDocCommentName (ds);
150 XmlNode n = GetDocCommentNode (mc, name);
152 XmlElement el = n as XmlElement;
154 mc.OnGenerateDocComment (ds, el);
156 // FIXME: it could be done with XmlReader
157 foreach (XmlElement inc in n.SelectNodes (".//include"))
158 HandleInclude (mc, inc);
160 // FIXME: it could be done with XmlReader
161 DeclSpace dsTarget = mc as DeclSpace;
162 if (dsTarget == null)
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);
173 n.WriteTo (RootContext.Documentation.XmlCommentOutput);
175 else if (mc.IsExposedFromAssembly (ds)) {
176 Constructor c = mc as Constructor;
177 if (c == null || !c.IsDefault ())
178 Report.Warning (1591, 4, mc.Location,
179 "Missing XML comment for publicly visible type or member `{0}'", mc.GetSignatureForError ());
184 // Processes "include" element. Check included file and
185 // embed the document content inside this documentation node.
187 private static void HandleInclude (MemberCore mc, XmlElement el)
189 string file = el.GetAttribute ("file");
190 string path = el.GetAttribute ("path");
192 Report.Warning (1590, 1, mc.Location, "Invalid XML `include' element. Missing `file' attribute");
193 el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" Include tag is invalid "), el);
195 else if (path == "") {
196 Report.Warning (1590, 1, mc.Location, "Invalid XML `include' element. Missing `path' attribute");
197 el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" Include tag is invalid "), el);
200 XmlDocument doc = RootContext.Documentation.StoredDocuments [file] as XmlDocument;
203 doc = new XmlDocument ();
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);
211 bool keepIncludeNode = false;
214 XmlNodeList nl = doc.SelectNodes (path);
216 el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" No matching elements were found for the include tag embedded here. "), el);
218 keepIncludeNode = true;
220 foreach (XmlNode n in nl)
221 el.ParentNode.InsertBefore (el.OwnerDocument.ImportNode (n, true), el);
222 } catch (Exception ex) {
223 el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" Failed to insert some or all of included XML "), el);
224 Report.Warning (1589, 1, mc.Location, "Unable to include XML fragment `{0}' of file `{1}' ({2})", path, file, ex.Message);
227 if (!keepIncludeNode)
228 el.ParentNode.RemoveChild (el);
233 // Handles <see> elements.
235 private static void HandleSee (MemberCore mc,
236 DeclSpace ds, XmlElement see)
238 HandleXrefCommon (mc, ds, see);
242 // Handles <seealso> elements.
244 private static void HandleSeeAlso (MemberCore mc,
245 DeclSpace ds, XmlElement seealso)
247 HandleXrefCommon (mc, ds, seealso);
251 // Handles <exception> elements.
253 private static void HandleException (MemberCore mc,
254 DeclSpace ds, XmlElement seealso)
256 HandleXrefCommon (mc, ds, seealso);
259 static readonly char [] wsChars =
260 new char [] {' ', '\t', '\n', '\r'};
263 // returns a full runtime type name from a name which might
264 // be C# specific type name.
266 private static Type FindDocumentedType (MemberCore mc, string name, DeclSpace ds, string cref)
268 bool isArray = false;
269 string identifier = name;
270 if (name [name.Length - 1] == ']') {
271 string tmp = name.Substring (0, name.Length - 1).Trim (wsChars);
272 if (tmp [tmp.Length - 1] == '[') {
273 identifier = tmp.Substring (0, tmp.Length - 1).Trim (wsChars);
277 Type t = FindDocumentedTypeNonArray (mc, identifier, ds, cref);
278 if (t != null && isArray)
279 t = Array.CreateInstance (t, 0).GetType ();
283 private static Type FindDocumentedTypeNonArray (MemberCore mc,
284 string identifier, DeclSpace ds, string cref)
286 switch (identifier) {
290 return typeof (uint);
292 return typeof (short);
294 return typeof (ushort);
296 return typeof (long);
298 return typeof (ulong);
300 return typeof (float);
302 return typeof (double);
304 return typeof (char);
306 return typeof (decimal);
308 return typeof (byte);
310 return typeof (sbyte);
312 return typeof (object);
314 return typeof (bool);
316 return typeof (string);
318 return typeof (void);
320 FullNamedExpression e = ds.LookupType (identifier, mc.Location, false);
322 if (!(e is TypeExpr))
326 int index = identifier.LastIndexOf ('.');
330 Type parent = FindDocumentedType (mc, identifier.Substring (0, index), ds, cref);
333 // no need to detect warning 419 here
334 return FindDocumentedMember (mc, parent,
335 identifier.Substring (index + 1),
337 ds, out warn, cref, false, null) as Type;
340 private static MemberInfo [] empty_member_infos =
343 private static MemberInfo [] FindMethodBase (Type type,
344 BindingFlags bindingFlags, MethodSignature signature)
346 MemberList ml = TypeManager.FindMembers (
348 MemberTypes.Constructor | MemberTypes.Method | MemberTypes.Property | MemberTypes.Custom,
350 MethodSignature.method_signature_filter,
353 return empty_member_infos;
355 return FilterOverridenMembersOut (type, (MemberInfo []) ml);
358 static bool IsOverride (PropertyInfo deriv_prop, PropertyInfo base_prop)
360 if (!Invocation.IsAncestralType (base_prop.DeclaringType, deriv_prop.DeclaringType))
363 Type [] deriv_pd = TypeManager.GetArgumentTypes (deriv_prop);
364 Type [] base_pd = TypeManager.GetArgumentTypes (base_prop);
366 if (deriv_pd.Length != base_pd.Length)
369 for (int j = 0; j < deriv_pd.Length; ++j) {
370 if (deriv_pd [j] != base_pd [j])
372 Type ct = TypeManager.TypeToCoreType (deriv_pd [j]);
373 Type bt = TypeManager.TypeToCoreType (base_pd [j]);
382 private static MemberInfo [] FilterOverridenMembersOut (
383 Type type, MemberInfo [] ml)
386 return empty_member_infos;
387 if (type.IsInterface)
390 ArrayList al = new ArrayList (ml.Length);
391 for (int i = 0; i < ml.Length; i++) {
392 // Interface methods which are returned
393 // from the filter must exist in the
394 // target type (if there is only a
395 // private implementation, then the
396 // filter should not return it.)
397 // This filtering is required to
398 // deambiguate results.
400 // It is common to properties, so check it here.
401 if (ml [i].DeclaringType.IsInterface)
403 MethodBase mx = ml [i] as MethodBase;
404 PropertyInfo px = ml [i] as PropertyInfo;
405 if (mx != null || px != null) {
406 bool overriden = false;
407 for (int j = 0; j < ml.Length; j++) {
410 MethodBase my = ml [j] as MethodBase;
411 if (mx != null && my != null &&
412 Invocation.IsOverride (my, mx)) {
418 PropertyInfo py = ml [j] as PropertyInfo;
419 if (px != null && py != null &&
420 IsOverride (py, px)) {
430 return al.ToArray (typeof (MemberInfo)) as MemberInfo [];
434 // Returns a MemberInfo that is referenced in XML documentation
435 // (by "see" or "seealso" elements).
437 private static MemberInfo FindDocumentedMember (MemberCore mc,
438 Type type, string memberName, Type [] paramList,
439 DeclSpace ds, out int warningType, string cref,
440 bool warn419, string nameForError)
443 MethodSignature msig = new MethodSignature (memberName, null, paramList);
444 MemberInfo [] mis = FindMethodBase (type,
445 BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance,
448 if (warn419 && mis.Length > 0) {
449 if (IsAmbiguous (mis))
450 Report419 (mc, nameForError, mis);
454 if (paramList.Length == 0) {
455 // search for fields/events etc.
456 mis = TypeManager.MemberLookup (type, null,
457 type, MemberTypes.All,
458 BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance,
460 mis = FilterOverridenMembersOut (type, mis);
461 if (mis == null || mis.Length == 0)
463 if (warn419 && IsAmbiguous (mis))
464 Report419 (mc, nameForError, mis);
468 // search for operators (whose parameters exactly
469 // matches with the list) and possibly report CS1581.
471 string returnTypeName = null;
472 if (memberName.StartsWith ("implicit operator ")) {
473 oper = "op_Implicit";
474 returnTypeName = memberName.Substring (18).Trim (wsChars);
476 else if (memberName.StartsWith ("explicit operator ")) {
477 oper = "op_Explicit";
478 returnTypeName = memberName.Substring (18).Trim (wsChars);
480 else if (memberName.StartsWith ("operator ")) {
481 oper = memberName.Substring (9).Trim (wsChars);
483 // either unary or binary
485 oper = paramList.Length == 2 ?
486 Binary.oper_names [(int) Binary.Operator.Addition] :
487 Unary.oper_names [(int) Unary.Operator.UnaryPlus];
490 oper = paramList.Length == 2 ?
491 Binary.oper_names [(int) Binary.Operator.Subtraction] :
492 Unary.oper_names [(int) Unary.Operator.UnaryNegation];
496 oper = Unary.oper_names [(int) Unary.Operator.LogicalNot]; break;
498 oper = Unary.oper_names [(int) Unary.Operator.OnesComplement]; break;
501 oper = "op_Increment"; break;
503 oper = "op_Decrement"; break;
505 oper = "op_True"; break;
507 oper = "op_False"; break;
510 oper = Binary.oper_names [(int) Binary.Operator.Multiply]; break;
512 oper = Binary.oper_names [(int) Binary.Operator.Division]; break;
514 oper = Binary.oper_names [(int) Binary.Operator.Modulus]; break;
516 oper = Binary.oper_names [(int) Binary.Operator.BitwiseAnd]; break;
518 oper = Binary.oper_names [(int) Binary.Operator.BitwiseOr]; break;
520 oper = Binary.oper_names [(int) Binary.Operator.ExclusiveOr]; break;
522 oper = Binary.oper_names [(int) Binary.Operator.LeftShift]; break;
524 oper = Binary.oper_names [(int) Binary.Operator.RightShift]; break;
526 oper = Binary.oper_names [(int) Binary.Operator.Equality]; break;
528 oper = Binary.oper_names [(int) Binary.Operator.Inequality]; break;
530 oper = Binary.oper_names [(int) Binary.Operator.LessThan]; break;
532 oper = Binary.oper_names [(int) Binary.Operator.GreaterThan]; break;
534 oper = Binary.oper_names [(int) Binary.Operator.LessThanOrEqual]; break;
536 oper = Binary.oper_names [(int) Binary.Operator.GreaterThanOrEqual]; break;
539 Report.Warning (1020, 1, mc.Location, "Overloadable {0} operator is expected", paramList.Length == 2 ? "binary" : "unary");
540 Report.Warning (1584, 1, mc.Location, "XML comment on `{0}' has syntactically incorrect cref attribute `{1}'",
541 mc.GetSignatureForError (), cref);
545 // here we still don't consider return type (to
546 // detect CS1581 or CS1002+CS1584).
547 msig = new MethodSignature (oper, null, paramList);
549 mis = FindMethodBase (type,
550 BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance,
553 return null; // CS1574
554 MemberInfo mi = mis [0];
555 Type expected = mi is MethodInfo ?
556 ((MethodInfo) mi).ReturnType :
558 ((PropertyInfo) mi).PropertyType :
560 if (returnTypeName != null) {
561 Type returnType = FindDocumentedType (mc, returnTypeName, ds, cref);
562 if (returnType == null || returnType != expected) {
564 Report.Warning (1581, 1, mc.Location, "Invalid return type in XML comment cref attribute `{0}'", cref);
571 private static bool IsAmbiguous (MemberInfo [] members)
573 if (members.Length < 2)
575 if (members.Length > 2)
577 if (members [0] is EventInfo && members [1] is FieldInfo)
579 if (members [1] is EventInfo && members [0] is FieldInfo)
585 // Processes "see" or "seealso" elements.
586 // Checks cref attribute.
588 private static void HandleXrefCommon (MemberCore mc,
589 DeclSpace ds, XmlElement xref)
591 string cref = xref.GetAttribute ("cref").Trim (wsChars);
592 // when, XmlReader, "if (cref == null)"
593 if (!xref.HasAttribute ("cref"))
595 if (cref.Length == 0)
596 Report.Warning (1001, 1, mc.Location, "Identifier expected");
597 // ... and continue until CS1584.
599 string signature; // "x:" are stripped
600 string name; // method invokation "(...)" are removed
601 string parameters; // method parameter list
603 // strip 'T:' 'M:' 'F:' 'P:' 'E:' etc.
604 // Here, MS ignores its member kind. No idea why.
605 if (cref.Length > 2 && cref [1] == ':')
606 signature = cref.Substring (2).Trim (wsChars);
610 int parensPos = signature.IndexOf ('(');
611 int bracePos = parensPos >= 0 ? -1 :
612 signature.IndexOf ('[');
613 if (parensPos > 0 && signature [signature.Length - 1] == ')') {
614 name = signature.Substring (0, parensPos).Trim (wsChars);
615 parameters = signature.Substring (parensPos + 1, signature.Length - parensPos - 2).Trim (wsChars);
617 else if (bracePos > 0 && signature [signature.Length - 1] == ']') {
618 name = signature.Substring (0, bracePos).Trim (wsChars);
619 parameters = signature.Substring (bracePos + 1, signature.Length - bracePos - 2).Trim (wsChars);
623 parameters = String.Empty;
625 Normalize (mc, ref name);
627 string identifier = GetBodyIdentifierFromName (name);
629 // Check if identifier is valid.
630 // This check is not necessary to mark as error, but
631 // csc specially reports CS1584 for wrong identifiers.
632 string [] nameElems = identifier.Split ('.');
633 for (int i = 0; i < nameElems.Length; i++) {
634 string nameElem = GetBodyIdentifierFromName (nameElems [i]);
636 Normalize (mc, ref nameElem);
637 if (!Tokenizer.IsValidIdentifier (nameElem)
638 && nameElem.IndexOf ("operator") < 0) {
639 Report.Warning (1584, 1, mc.Location, "XML comment on `{0}' has syntactically incorrect cref attribute `{1}'",
640 mc.GetSignatureForError (), cref);
641 xref.SetAttribute ("cref", "!:" + signature);
646 // check if parameters are valid
647 Type [] parameterTypes = Type.EmptyTypes;
648 if (parameters.Length > 0) {
649 string [] paramList = parameters.Split (',');
650 ArrayList plist = new ArrayList ();
651 for (int i = 0; i < paramList.Length; i++) {
652 string paramTypeName = paramList [i].Trim (wsChars);
653 Normalize (mc, ref paramTypeName);
654 Type paramType = FindDocumentedType (mc, paramTypeName, ds, cref);
655 if (paramType == null) {
656 Report.Warning (1580, 1, mc.Location, "Invalid type for parameter `{0}' in XML comment cref attribute `{1}'",
657 (i + 1).ToString (), cref);
660 plist.Add (paramType);
662 parameterTypes = plist.ToArray (typeof (Type)) as Type [];
665 Type type = FindDocumentedType (mc, name, ds, cref);
667 // delegate must not be referenced with args
668 && (!type.IsSubclassOf (typeof (System.Delegate))
669 || parameterTypes.Length == 0)) {
670 string result = type.FullName.Replace ("+", ".")
671 + (bracePos < 0 ? String.Empty : signature.Substring (bracePos));
672 xref.SetAttribute ("cref", "T:" + result);
676 // don't use identifier here. System[] is not alloed.
677 if (RootNamespace.Global.IsNamespace (name)) {
678 xref.SetAttribute ("cref", "N:" + name);
679 return; // a namespace
682 int period = name.LastIndexOf ('.');
684 string typeName = name.Substring (0, period);
685 string memberName = name.Substring (period + 1);
686 Normalize (mc, ref memberName);
687 type = FindDocumentedType (mc, typeName, ds, cref);
690 MemberInfo mi = FindDocumentedMember (mc, type, memberName, parameterTypes, ds, out warnResult, cref, true, name);
694 xref.SetAttribute ("cref", GetMemberDocHead (mi.MemberType) + type.FullName.Replace ("+", ".") + "." + memberName + GetParametersFormatted (mi));
695 return; // a member of a type
701 MemberInfo mi = FindDocumentedMember (mc, ds.TypeBuilder, name, parameterTypes, ds, out warnResult, cref, true, name);
705 xref.SetAttribute ("cref", GetMemberDocHead (mi.MemberType) + ds.TypeBuilder.FullName.Replace ("+", ".") + "." + name + GetParametersFormatted (mi));
706 return; // local member name
710 Report.Warning (1574, 1, mc.Location, "XML comment on `{0}' has cref attribute `{1}' that could not be resolved",
711 mc.GetSignatureForError (), cref);
713 xref.SetAttribute ("cref", "!:" + name);
716 static string GetParametersFormatted (MemberInfo mi)
718 MethodBase mb = mi as MethodBase;
719 bool isSetter = false;
720 PropertyInfo pi = mi as PropertyInfo;
722 mb = pi.GetGetMethod ();
725 mb = pi.GetSetMethod ();
731 ParameterData parameters = TypeManager.GetParameterData (mb);
732 if (parameters == null || parameters.Count == 0)
735 StringBuilder sb = new StringBuilder ();
737 for (int i = 0; i < parameters.Count; i++) {
738 if (isSetter && i + 1 == parameters.Count)
739 break; // skip "value".
742 Type t = parameters.ParameterType (i);
743 sb.Append (t.FullName.Replace ('+', '.').Replace ('&', '@'));
746 return sb.ToString ();
749 static string GetBodyIdentifierFromName (string name)
751 string identifier = name;
753 if (name.Length > 0 && name [name.Length - 1] == ']') {
754 string tmp = name.Substring (0, name.Length - 1).Trim (wsChars);
755 int last = tmp.LastIndexOf ('[');
757 identifier = tmp.Substring (0, last).Trim (wsChars);
763 static void Report419 (MemberCore mc, string memberName, MemberInfo [] mis)
765 Report.Warning (419, 3, mc.Location,
766 "Ambiguous reference in cref attribute `{0}'. Assuming `{1}' but other overloads including `{2}' have also matched",
768 TypeManager.GetFullNameSignature (mis [0]),
769 TypeManager.GetFullNameSignature (mis [1]));
773 // Get a prefix from member type for XML documentation (used
774 // to formalize cref target name).
776 static string GetMemberDocHead (MemberTypes type)
779 case MemberTypes.Constructor:
780 case MemberTypes.Method:
782 case MemberTypes.Event:
784 case MemberTypes.Field:
786 case MemberTypes.NestedType:
787 case MemberTypes.TypeInfo:
789 case MemberTypes.Property:
798 // Returns a string that represents the signature for this
799 // member which should be used in XML documentation.
801 public static string GetMethodDocCommentName (MethodCore mc, DeclSpace ds)
803 Parameter [] plist = mc.Parameters.FixedParameters;
804 string paramSpec = String.Empty;
806 StringBuilder psb = new StringBuilder ();
807 foreach (Parameter p in plist) {
808 psb.Append (psb.Length != 0 ? "," : "(");
809 psb.Append (p.ExternalType ().FullName.Replace ("+", ".").Replace ('&', '@'));
811 paramSpec = psb.ToString ();
814 if (paramSpec.Length > 0)
817 string name = mc is Constructor ? "#ctor" : mc.Name;
818 string suffix = String.Empty;
819 Operator op = mc as Operator;
821 switch (op.OperatorType) {
822 case Operator.OpType.Implicit:
823 case Operator.OpType.Explicit:
824 suffix = "~" + op.OperatorMethodBuilder.ReturnType.FullName.Replace ('+', '.');
828 return String.Concat (mc.DocCommentHeader, ds.Name, ".", name, paramSpec, suffix);
832 // Raised (and passed an XmlElement that contains the comment)
833 // when GenerateDocComment is writing documentation expectedly.
835 // FIXME: with a few effort, it could be done with XmlReader,
836 // that means removal of DOM use.
838 internal static void OnMethodGenerateDocComment (
839 MethodCore mc, DeclSpace ds, XmlElement el)
841 Hashtable paramTags = new Hashtable ();
842 foreach (XmlElement pelem in el.SelectNodes ("param")) {
844 string xname = pelem.GetAttribute ("name");
846 continue; // really? but MS looks doing so
847 if (xname != "" && mc.Parameters.GetParameterByName (xname, out i) == null)
848 Report.Warning (1572, 2, mc.Location, "XML comment on `{0}' has a param tag for `{1}', but there is no parameter by that name",
849 mc.GetSignatureForError (), xname);
850 else if (paramTags [xname] != null)
851 Report.Warning (1571, 2, mc.Location, "XML comment on `{0}' has a duplicate param tag for `{1}'",
852 mc.GetSignatureForError (), xname);
853 paramTags [xname] = xname;
855 Parameter [] plist = mc.Parameters.FixedParameters;
856 foreach (Parameter p in plist) {
857 if (paramTags.Count > 0 && paramTags [p.Name] == null)
858 Report.Warning (1573, 4, mc.Location, "Parameter `{0}' has no matching param tag in the XML comment for `{1}'",
859 p.Name, mc.GetSignatureForError ());
863 private static void Normalize (MemberCore mc, ref string name)
865 if (name.Length > 0 && name [0] == '@')
866 name = name.Substring (1);
867 else if (name == "this")
869 else if (Tokenizer.IsKeyword (name) && !IsTypeName (name))
870 Report.Warning (1041, 1, mc.Location, "Identifier expected. `{0}' is a keyword", name);
873 private static bool IsTypeName (string name)
899 // Implements XML documentation generation.
901 public class Documentation
903 public Documentation (string xml_output_filename)
905 docfilename = xml_output_filename;
906 XmlDocumentation = new XmlDocument ();
907 XmlDocumentation.PreserveWhitespace = false;
910 private string docfilename;
913 // Used to create element which helps well-formedness checking.
915 public XmlDocument XmlDocumentation;
918 // The output for XML documentation.
920 public XmlWriter XmlCommentOutput;
923 // Stores XmlDocuments that are included in XML documentation.
924 // Keys are included filenames, values are XmlDocuments.
926 public Hashtable StoredDocuments = new Hashtable ();
929 // Stores comments on partial types (should handle uniquely).
930 // Keys are PartialContainers, values are comment strings
931 // (didn't use StringBuilder; usually we have just 2 or more).
933 public IDictionary PartialComments = new ListDictionary ();
936 // Outputs XML documentation comment from tokenized comments.
938 public bool OutputDocComment (string asmfilename)
940 XmlTextWriter w = null;
942 w = new XmlTextWriter (docfilename, null);
944 w.Formatting = Formatting.Indented;
945 w.WriteStartDocument ();
946 w.WriteStartElement ("doc");
947 w.WriteStartElement ("assembly");
948 w.WriteStartElement ("name");
949 w.WriteString (Path.ChangeExtension (asmfilename, null));
950 w.WriteEndElement (); // name
951 w.WriteEndElement (); // assembly
952 w.WriteStartElement ("members");
953 XmlCommentOutput = w;
954 GenerateDocComment ();
955 w.WriteFullEndElement (); // members
956 w.WriteEndElement ();
957 w.WriteWhitespace (Environment.NewLine);
958 w.WriteEndDocument ();
960 } catch (Exception ex) {
961 Report.Error (1569, "Error generating XML documentation file `{0}' (`{1}')", docfilename, ex.Message);
970 // Fixes full type name of each documented types/members up.
972 public void GenerateDocComment ()
974 TypeContainer root = RootContext.Tree.Types;
975 if (root.Interfaces != null)
976 foreach (Interface i in root.Interfaces)
977 DocUtil.GenerateTypeDocComment (i, null);
979 if (root.Types != null)
980 foreach (TypeContainer tc in root.Types)
981 DocUtil.GenerateTypeDocComment (tc, null);
983 if (root.Parts != null) {
984 IDictionary comments = PartialComments;
985 foreach (ClassPart cp in root.Parts) {
986 if (cp.DocComment == null)
992 if (root.Delegates != null)
993 foreach (Delegate d in root.Delegates)
994 DocUtil.GenerateDocComment (d, null);
996 if (root.Enums != null)
997 foreach (Enum e in root.Enums)
998 e.GenerateDocComment (null);
1000 IDictionary table = new ListDictionary ();
1001 foreach (ClassPart cp in PartialComments.Keys) {
1002 // FIXME: IDictionary does not guarantee that the keys will be
1003 // accessed in the order they were added.
1004 table [cp.PartialContainer] += cp.DocComment;
1006 foreach (PartialContainer pc in table.Keys) {
1007 pc.DocComment = table [pc] as string;
1008 DocUtil.GenerateDocComment (pc, null);