X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=blobdiff_plain;f=mcs%2Fmcs%2Fdoc.cs;h=2eb06b554237663998241f48097da9017a656b39;hb=af923bf52b6745a7cacd4aef5acb4c8720f0dd5a;hp=75af12994b2b753a2fa70faea608a792020503c7;hpb=c0ad1558af3c96b8d1eacc8535f3e0be0e43a3ed;p=mono.git diff --git a/mcs/mcs/doc.cs b/mcs/mcs/doc.cs index 75af12994b2..2eb06b55423 100644 --- a/mcs/mcs/doc.cs +++ b/mcs/mcs/doc.cs @@ -4,16 +4,14 @@ // Author: // Atsushi Enomoto // -// Licensed under the terms of the GNU GPL +// Dual licensed under the terms of the MIT X11 or GNU GPL // -// (C) 2004 Novell, Inc. +// Copyright 2004 Novell, Inc. // // -#if ! BOOTSTRAP_WITH_OLDLIB using System; -using System.Collections; -using System.Collections.Specialized; +using System.Collections.Generic; using System.IO; using System.Reflection; using System.Reflection.Emit; @@ -31,7 +29,7 @@ namespace Mono.CSharp { // // Support class for XML documentation. // - public class DocUtil + static class DocUtil { // TypeContainer @@ -40,9 +38,9 @@ namespace Mono.CSharp { // handle warning report. // internal static void GenerateTypeDocComment (TypeContainer t, - DeclSpace ds) + DeclSpace ds, Report Report) { - GenerateDocComment (t, ds); + GenerateDocComment (t, ds, Report); if (t.DefaultStaticConstructor != null) t.DefaultStaticConstructor.GenerateDocComment (t); @@ -55,18 +53,9 @@ namespace Mono.CSharp { foreach (TypeContainer tc in t.Types) tc.GenerateDocComment (t); - if (t.Parts != null) { - IDictionary comments = RootContext.Documentation.PartialComments; - foreach (ClassPart cp in t.Parts) { - if (cp.DocComment == null) - continue; - comments [cp] = cp; - } - } - - if (t.Enums != null) - foreach (Enum en in t.Enums) - en.GenerateDocComment (t); + if (t.Delegates != null) + foreach (Delegate de in t.Delegates) + de.GenerateDocComment (t); if (t.Constants != null) foreach (Const c in t.Constants) @@ -89,7 +78,7 @@ namespace Mono.CSharp { p.GenerateDocComment (t); if (t.Methods != null) - foreach (Method m in t.Methods) + foreach (MethodOrOperator m in t.Methods) m.GenerateDocComment (t); if (t.Operators != null) @@ -98,11 +87,11 @@ namespace Mono.CSharp { } // MemberCore - private static readonly string lineHead = + private static readonly string line_head = Environment.NewLine + " "; private static XmlNode GetDocCommentNode (MemberCore mc, - string name) + string name, Report Report) { // FIXME: It could be even optimizable as not // to use XmlDocument. But anyways the nodes @@ -127,10 +116,10 @@ namespace Mono.CSharp { if (s.Length > 0) split [j++] = s; } - el.InnerXml = lineHead + String.Join ( - lineHead, split, 0, j); + el.InnerXml = line_head + String.Join ( + line_head, split, 0, j); return el; - } catch (XmlException ex) { + } catch (Exception ex) { Report.Warning (1570, 1, mc.Location, "XML comment on `{0}' has non-well-formed XML ({1})", name, ex.Message); XmlComment com = doc.CreateComment (String.Format ("FIXME: Invalid documentation markup was found for member {0}", name)); return com; @@ -142,37 +131,45 @@ namespace Mono.CSharp { // handle warning report. // internal static void GenerateDocComment (MemberCore mc, - DeclSpace ds) + DeclSpace ds, Report Report) { if (mc.DocComment != null) { string name = mc.GetDocCommentName (ds); - XmlNode n = GetDocCommentNode (mc, name); + XmlNode n = GetDocCommentNode (mc, name, Report); XmlElement el = n as XmlElement; if (el != null) { - mc.OnGenerateDocComment (ds, el); + mc.OnGenerateDocComment (el); // FIXME: it could be done with XmlReader - foreach (XmlElement inc in n.SelectNodes (".//include")) - HandleInclude (mc, inc); + XmlNodeList nl = n.SelectNodes (".//include"); + if (nl.Count > 0) { + // It could result in current node removal, so prepare another list to iterate. + var al = new List (nl.Count); + foreach (XmlNode inc in nl) + al.Add (inc); + foreach (XmlElement inc in al) + if (!HandleInclude (mc, inc, Report)) + inc.ParentNode.RemoveChild (inc); + } // FIXME: it could be done with XmlReader - DeclSpace dsTarget = mc as DeclSpace; - if (dsTarget == null) - dsTarget = ds; + DeclSpace ds_target = mc as DeclSpace; + if (ds_target == null) + ds_target = ds; foreach (XmlElement see in n.SelectNodes (".//see")) - HandleSee (mc, dsTarget, see); + HandleSee (mc, ds_target, see, Report); foreach (XmlElement seealso in n.SelectNodes (".//seealso")) - HandleSeeAlso (mc, dsTarget, seealso); + HandleSeeAlso (mc, ds_target, seealso ,Report); foreach (XmlElement see in n.SelectNodes (".//exception")) - HandleException (mc, dsTarget, see); + HandleException (mc, ds_target, see, Report); } n.WriteTo (RootContext.Documentation.XmlCommentOutput); } - else if (mc.IsExposedFromAssembly (ds)) { + else if (mc.IsExposedFromAssembly ()) { Constructor c = mc as Constructor; if (c == null || !c.IsDefault ()) Report.Warning (1591, 4, mc.Location, @@ -184,21 +181,24 @@ namespace Mono.CSharp { // Processes "include" element. Check included file and // embed the document content inside this documentation node. // - private static void HandleInclude (MemberCore mc, XmlElement el) + private static bool HandleInclude (MemberCore mc, XmlElement el, Report Report) { + bool keep_include_node = false; string file = el.GetAttribute ("file"); string path = el.GetAttribute ("path"); if (file == "") { Report.Warning (1590, 1, mc.Location, "Invalid XML `include' element. Missing `file' attribute"); el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" Include tag is invalid "), el); + keep_include_node = true; } - else if (path == "") { + else if (path.Length == 0) { Report.Warning (1590, 1, mc.Location, "Invalid XML `include' element. Missing `path' attribute"); el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" Include tag is invalid "), el); + keep_include_node = true; } else { - XmlDocument doc = RootContext.Documentation.StoredDocuments [file] as XmlDocument; - if (doc == null) { + XmlDocument doc; + if (!RootContext.Documentation.StoredDocuments.TryGetValue (file, out doc)) { try { doc = new XmlDocument (); doc.Load (file); @@ -208,14 +208,13 @@ namespace Mono.CSharp { Report.Warning (1592, 1, mc.Location, "Badly formed XML in included comments file -- `{0}'", file); } } - bool keepIncludeNode = false; if (doc != null) { try { XmlNodeList nl = doc.SelectNodes (path); if (nl.Count == 0) { el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" No matching elements were found for the include tag embedded here. "), el); - keepIncludeNode = true; + keep_include_node = true; } foreach (XmlNode n in nl) el.ParentNode.InsertBefore (el.OwnerDocument.ImportNode (n, true), el); @@ -224,36 +223,35 @@ namespace Mono.CSharp { Report.Warning (1589, 1, mc.Location, "Unable to include XML fragment `{0}' of file `{1}' ({2})", path, file, ex.Message); } } - if (!keepIncludeNode) - el.ParentNode.RemoveChild (el); } + return keep_include_node; } // // Handles elements. // private static void HandleSee (MemberCore mc, - DeclSpace ds, XmlElement see) + DeclSpace ds, XmlElement see, Report r) { - HandleXrefCommon (mc, ds, see); + HandleXrefCommon (mc, ds, see, r); } // // Handles elements. // private static void HandleSeeAlso (MemberCore mc, - DeclSpace ds, XmlElement seealso) + DeclSpace ds, XmlElement seealso, Report r) { - HandleXrefCommon (mc, ds, seealso); + HandleXrefCommon (mc, ds, seealso, r); } // // Handles elements. // private static void HandleException (MemberCore mc, - DeclSpace ds, XmlElement seealso) + DeclSpace ds, XmlElement seealso, Report r) { - HandleXrefCommon (mc, ds, seealso); + HandleXrefCommon (mc, ds, seealso, r); } static readonly char [] wsChars = @@ -263,61 +261,61 @@ namespace Mono.CSharp { // returns a full runtime type name from a name which might // be C# specific type name. // - private static Type FindDocumentedType (MemberCore mc, string name, DeclSpace ds, string cref) + private static Type FindDocumentedType (MemberCore mc, string name, DeclSpace ds, string cref, Report r) { - bool isArray = false; + bool is_array = false; string identifier = name; if (name [name.Length - 1] == ']') { string tmp = name.Substring (0, name.Length - 1).Trim (wsChars); if (tmp [tmp.Length - 1] == '[') { identifier = tmp.Substring (0, tmp.Length - 1).Trim (wsChars); - isArray = true; + is_array = true; } } - Type t = FindDocumentedTypeNonArray (mc, identifier, ds, cref); - if (t != null && isArray) + Type t = FindDocumentedTypeNonArray (mc, identifier, ds, cref, r); + if (t != null && is_array) t = Array.CreateInstance (t, 0).GetType (); return t; } private static Type FindDocumentedTypeNonArray (MemberCore mc, - string identifier, DeclSpace ds, string cref) + string identifier, DeclSpace ds, string cref, Report r) { switch (identifier) { case "int": - return typeof (int); + return TypeManager.int32_type; case "uint": - return typeof (uint); + return TypeManager.uint32_type; case "short": - return typeof (short); + return TypeManager.short_type;; case "ushort": - return typeof (ushort); + return TypeManager.ushort_type; case "long": - return typeof (long); + return TypeManager.int64_type; case "ulong": - return typeof (ulong); + return TypeManager.uint64_type;; case "float": - return typeof (float); + return TypeManager.float_type;; case "double": - return typeof (double); + return TypeManager.double_type; case "char": - return typeof (char); + return TypeManager.char_type;; case "decimal": - return typeof (decimal); + return TypeManager.decimal_type;; case "byte": - return typeof (byte); + return TypeManager.byte_type;; case "sbyte": - return typeof (sbyte); + return TypeManager.sbyte_type;; case "object": - return typeof (object); + return TypeManager.object_type;; case "bool": - return typeof (bool); + return TypeManager.bool_type;; case "string": - return typeof (string); + return TypeManager.string_type;; case "void": - return typeof (void); + return TypeManager.void_type;; } - FullNamedExpression e = ds.LookupType (identifier, mc.Location, false); + FullNamedExpression e = ds.LookupNamespaceOrType (identifier, mc.Location, false); if (e != null) { if (!(e is TypeExpr)) return null; @@ -327,41 +325,40 @@ namespace Mono.CSharp { if (index < 0) return null; int warn; - Type parent = FindDocumentedType (mc, identifier.Substring (0, index), ds, cref); + Type parent = FindDocumentedType (mc, identifier.Substring (0, index), ds, cref, r); if (parent == null) return null; // no need to detect warning 419 here return FindDocumentedMember (mc, parent, identifier.Substring (index + 1), - Type.EmptyTypes, - ds, out warn, cref, false, null) as Type; + null, ds, out warn, cref, false, null, r).Member as Type; } private static MemberInfo [] empty_member_infos = new MemberInfo [0]; private static MemberInfo [] FindMethodBase (Type type, - BindingFlags bindingFlags, MethodSignature signature) + BindingFlags binding_flags, MethodSignature signature) { MemberList ml = TypeManager.FindMembers ( type, MemberTypes.Constructor | MemberTypes.Method | MemberTypes.Property | MemberTypes.Custom, - bindingFlags, + binding_flags, MethodSignature.method_signature_filter, signature); if (ml == null) return empty_member_infos; - return FilterOverridenMembersOut (type, (MemberInfo []) ml); + return FilterOverridenMembersOut ((MemberInfo []) ml); } static bool IsOverride (PropertyInfo deriv_prop, PropertyInfo base_prop) { - if (!Invocation.IsAncestralType (base_prop.DeclaringType, deriv_prop.DeclaringType)) + if (!MethodGroupExpr.IsAncestralType (base_prop.DeclaringType, deriv_prop.DeclaringType)) return false; - Type [] deriv_pd = TypeManager.GetArgumentTypes (deriv_prop); - Type [] base_pd = TypeManager.GetArgumentTypes (base_prop); + Type [] deriv_pd = TypeManager.GetParameterData (deriv_prop).Types; + Type [] base_pd = TypeManager.GetParameterData (base_prop).Types; if (deriv_pd.Length != base_pd.Length) return false; @@ -380,26 +377,13 @@ namespace Mono.CSharp { } private static MemberInfo [] FilterOverridenMembersOut ( - Type type, MemberInfo [] ml) + MemberInfo [] ml) { if (ml == null) return empty_member_infos; - if (type.IsInterface) - return ml; - ArrayList al = new ArrayList (ml.Length); + var al = new List (ml.Length); for (int i = 0; i < ml.Length; i++) { - // Interface methods which are returned - // from the filter must exist in the - // target type (if there is only a - // private implementation, then the - // filter should not return it.) - // This filtering is required to - // deambiguate results. - // - // It is common to properties, so check it here. - if (ml [i].DeclaringType.IsInterface) - continue; MethodBase mx = ml [i] as MethodBase; PropertyInfo px = ml [i] as PropertyInfo; if (mx != null || px != null) { @@ -409,7 +393,7 @@ namespace Mono.CSharp { continue; MethodBase my = ml [j] as MethodBase; if (mx != null && my != null && - Invocation.IsOverride (my, mx)) { + MethodGroupExpr.IsOverride (my, mx)) { overriden = true; break; } @@ -427,116 +411,119 @@ namespace Mono.CSharp { } al.Add (ml [i]); } - return al.ToArray (typeof (MemberInfo)) as MemberInfo []; + return al.ToArray (); + } + + struct FoundMember + { + public static FoundMember Empty = new FoundMember (true); + + public bool IsEmpty; + public readonly MemberInfo Member; + public readonly Type Type; + + public FoundMember (bool regardless_of_this_value_its_empty) + { + IsEmpty = true; + Member = null; + Type = null; + } + + public FoundMember (Type found_type, MemberInfo member) + { + IsEmpty = false; + Type = found_type; + Member = member; + } } // // Returns a MemberInfo that is referenced in XML documentation // (by "see" or "seealso" elements). // - private static MemberInfo FindDocumentedMember (MemberCore mc, - Type type, string memberName, Type [] paramList, - DeclSpace ds, out int warningType, string cref, - bool warn419, string nameForError) + private static FoundMember FindDocumentedMember (MemberCore mc, + Type type, string member_name, Type [] param_list, + DeclSpace ds, out int warning_type, string cref, + bool warn419, string name_for_error, Report r) { - warningType = 0; - MethodSignature msig = new MethodSignature (memberName, null, paramList); - MemberInfo [] mis = FindMethodBase (type, - BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance, - msig); + for (; type != null; type = type.DeclaringType) { + MemberInfo mi = FindDocumentedMemberNoNest ( + mc, type, member_name, param_list, ds, + out warning_type, cref, warn419, + name_for_error, r); + if (mi != null) + return new FoundMember (type, mi); + } + warning_type = 0; + return FoundMember.Empty; + } - if (warn419 && mis.Length > 0) { - if (IsAmbiguous (mis)) - Report419 (mc, nameForError, mis); - return mis [0]; - } + private static MemberInfo FindDocumentedMemberNoNest ( + MemberCore mc, Type type, string member_name, + Type [] param_list, DeclSpace ds, out int warning_type, + string cref, bool warn419, string name_for_error, Report Report) + { + warning_type = 0; + MemberInfo [] mis; - if (paramList.Length == 0) { + if (param_list == null) { // search for fields/events etc. mis = TypeManager.MemberLookup (type, null, type, MemberTypes.All, BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance, - memberName, null); - mis = FilterOverridenMembersOut (type, mis); + member_name, null); + mis = FilterOverridenMembersOut (mis); if (mis == null || mis.Length == 0) return null; if (warn419 && IsAmbiguous (mis)) - Report419 (mc, nameForError, mis); + Report419 (mc, name_for_error, mis, Report); + return mis [0]; + } + + MethodSignature msig = new MethodSignature (member_name, null, param_list); + mis = FindMethodBase (type, + BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance, + msig); + + if (warn419 && mis.Length > 0) { + if (IsAmbiguous (mis)) + Report419 (mc, name_for_error, mis, Report); return mis [0]; } // search for operators (whose parameters exactly // matches with the list) and possibly report CS1581. string oper = null; - string returnTypeName = null; - if (memberName.StartsWith ("implicit operator ")) { - oper = "op_Implicit"; - returnTypeName = memberName.Substring (18).Trim (wsChars); + string return_type_name = null; + if (member_name.StartsWith ("implicit operator ")) { + Operator.GetMetadataName (Operator.OpType.Implicit); + return_type_name = member_name.Substring (18).Trim (wsChars); } - else if (memberName.StartsWith ("explicit operator ")) { - oper = "op_Explicit"; - returnTypeName = memberName.Substring (18).Trim (wsChars); + else if (member_name.StartsWith ("explicit operator ")) { + oper = Operator.GetMetadataName (Operator.OpType.Explicit); + return_type_name = member_name.Substring (18).Trim (wsChars); } - else if (memberName.StartsWith ("operator ")) { - oper = memberName.Substring (9).Trim (wsChars); + else if (member_name.StartsWith ("operator ")) { + oper = member_name.Substring (9).Trim (wsChars); switch (oper) { // either unary or binary case "+": - oper = paramList.Length == 2 ? - Binary.oper_names [(int) Binary.Operator.Addition] : - Unary.oper_names [(int) Unary.Operator.UnaryPlus]; + oper = param_list.Length == 2 ? + Operator.GetMetadataName (Operator.OpType.Addition) : + Operator.GetMetadataName (Operator.OpType.UnaryPlus); break; case "-": - oper = paramList.Length == 2 ? - Binary.oper_names [(int) Binary.Operator.Subtraction] : - Unary.oper_names [(int) Unary.Operator.UnaryNegation]; + oper = param_list.Length == 2 ? + Operator.GetMetadataName (Operator.OpType.Subtraction) : + Operator.GetMetadataName (Operator.OpType.UnaryNegation); break; - // unary - case "!": - oper = Unary.oper_names [(int) Unary.Operator.LogicalNot]; break; - case "~": - oper = Unary.oper_names [(int) Unary.Operator.OnesComplement]; break; - - case "++": - oper = "op_Increment"; break; - case "--": - oper = "op_Decrement"; break; - case "true": - oper = "op_True"; break; - case "false": - oper = "op_False"; break; - // binary - case "*": - oper = Binary.oper_names [(int) Binary.Operator.Multiply]; break; - case "/": - oper = Binary.oper_names [(int) Binary.Operator.Division]; break; - case "%": - oper = Binary.oper_names [(int) Binary.Operator.Modulus]; break; - case "&": - oper = Binary.oper_names [(int) Binary.Operator.BitwiseAnd]; break; - case "|": - oper = Binary.oper_names [(int) Binary.Operator.BitwiseOr]; break; - case "^": - oper = Binary.oper_names [(int) Binary.Operator.ExclusiveOr]; break; - case "<<": - oper = Binary.oper_names [(int) Binary.Operator.LeftShift]; break; - case ">>": - oper = Binary.oper_names [(int) Binary.Operator.RightShift]; break; - case "==": - oper = Binary.oper_names [(int) Binary.Operator.Equality]; break; - case "!=": - oper = Binary.oper_names [(int) Binary.Operator.Inequality]; break; - case "<": - oper = Binary.oper_names [(int) Binary.Operator.LessThan]; break; - case ">": - oper = Binary.oper_names [(int) Binary.Operator.GreaterThan]; break; - case "<=": - oper = Binary.oper_names [(int) Binary.Operator.LessThanOrEqual]; break; - case ">=": - oper = Binary.oper_names [(int) Binary.Operator.GreaterThanOrEqual]; break; default: - warningType = 1584; - Report.Warning (1020, 1, mc.Location, "Overloadable {0} operator is expected", paramList.Length == 2 ? "binary" : "unary"); + oper = Operator.GetMetadataName (oper); + if (oper != null) + break; + + warning_type = 1584; + Report.Warning (1020, 1, mc.Location, "Overloadable {0} operator is expected", param_list.Length == 2 ? "binary" : "unary"); Report.Warning (1584, 1, mc.Location, "XML comment on `{0}' has syntactically incorrect cref attribute `{1}'", mc.GetSignatureForError (), cref); return null; @@ -544,7 +531,7 @@ namespace Mono.CSharp { } // here we still don't consider return type (to // detect CS1581 or CS1002+CS1584). - msig = new MethodSignature (oper, null, paramList); + msig = new MethodSignature (oper, null, param_list); mis = FindMethodBase (type, BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance, @@ -557,10 +544,10 @@ namespace Mono.CSharp { mi is PropertyInfo ? ((PropertyInfo) mi).PropertyType : null; - if (returnTypeName != null) { - Type returnType = FindDocumentedType (mc, returnTypeName, ds, cref); + if (return_type_name != null) { + Type returnType = FindDocumentedType (mc, return_type_name, ds, cref, Report); if (returnType == null || returnType != expected) { - warningType = 1581; + warning_type = 1581; Report.Warning (1581, 1, mc.Location, "Invalid return type in XML comment cref attribute `{0}'", cref); return null; } @@ -586,7 +573,7 @@ namespace Mono.CSharp { // Checks cref attribute. // private static void HandleXrefCommon (MemberCore mc, - DeclSpace ds, XmlElement xref) + DeclSpace ds, XmlElement xref, Report Report) { string cref = xref.GetAttribute ("cref").Trim (wsChars); // when, XmlReader, "if (cref == null)" @@ -600,40 +587,47 @@ namespace Mono.CSharp { string name; // method invokation "(...)" are removed string parameters; // method parameter list - // strip 'T:' 'M:' 'F:' 'P:' 'E:' etc. - // Here, MS ignores its member kind. No idea why. + // When it found '?:' ('T:' 'M:' 'F:' 'P:' 'E:' etc.), + // MS ignores not only its member kind, but also + // the entire syntax correctness. Nor it also does + // type fullname resolution i.e. "T:List(int)" is kept + // as T:List(int), not + // T:System.Collections.Generic.List<System.Int32> if (cref.Length > 2 && cref [1] == ':') - signature = cref.Substring (2).Trim (wsChars); + return; else signature = cref; - int parensPos = signature.IndexOf ('('); - int bracePos = parensPos >= 0 ? -1 : + // Also note that without "T:" any generic type + // indication fails. + + int parens_pos = signature.IndexOf ('('); + int brace_pos = parens_pos >= 0 ? -1 : signature.IndexOf ('['); - if (parensPos > 0 && signature [signature.Length - 1] == ')') { - name = signature.Substring (0, parensPos).Trim (wsChars); - parameters = signature.Substring (parensPos + 1, signature.Length - parensPos - 2).Trim (wsChars); + if (parens_pos > 0 && signature [signature.Length - 1] == ')') { + name = signature.Substring (0, parens_pos).Trim (wsChars); + parameters = signature.Substring (parens_pos + 1, signature.Length - parens_pos - 2).Trim (wsChars); } - else if (bracePos > 0 && signature [signature.Length - 1] == ']') { - name = signature.Substring (0, bracePos).Trim (wsChars); - parameters = signature.Substring (bracePos + 1, signature.Length - bracePos - 2).Trim (wsChars); + else if (brace_pos > 0 && signature [signature.Length - 1] == ']') { + name = signature.Substring (0, brace_pos).Trim (wsChars); + parameters = signature.Substring (brace_pos + 1, signature.Length - brace_pos - 2).Trim (wsChars); } else { name = signature; - parameters = String.Empty; + parameters = null; } - Normalize (mc, ref name); + Normalize (mc, ref name, Report); string identifier = GetBodyIdentifierFromName (name); // Check if identifier is valid. // This check is not necessary to mark as error, but // csc specially reports CS1584 for wrong identifiers. - string [] nameElems = identifier.Split ('.'); - for (int i = 0; i < nameElems.Length; i++) { - string nameElem = GetBodyIdentifierFromName (nameElems [i]); + string [] name_elems = identifier.Split ('.'); + for (int i = 0; i < name_elems.Length; i++) { + string nameElem = GetBodyIdentifierFromName (name_elems [i]); if (i > 0) - Normalize (mc, ref nameElem); + Normalize (mc, ref nameElem, Report); if (!Tokenizer.IsValidIdentifier (nameElem) && nameElem.IndexOf ("operator") < 0) { Report.Warning (1584, 1, mc.Location, "XML comment on `{0}' has syntactically incorrect cref attribute `{1}'", @@ -644,69 +638,88 @@ namespace Mono.CSharp { } // check if parameters are valid - Type [] parameterTypes = Type.EmptyTypes; - if (parameters.Length > 0) { - string [] paramList = parameters.Split (','); - ArrayList plist = new ArrayList (); - for (int i = 0; i < paramList.Length; i++) { - string paramTypeName = paramList [i].Trim (wsChars); - Normalize (mc, ref paramTypeName); - Type paramType = FindDocumentedType (mc, paramTypeName, ds, cref); - if (paramType == null) { + Type [] parameter_types; + if (parameters == null) + parameter_types = null; + else if (parameters.Length == 0) + parameter_types = Type.EmptyTypes; + else { + string [] param_list = parameters.Split (','); + var plist = new List (); + for (int i = 0; i < param_list.Length; i++) { + string param_type_name = param_list [i].Trim (wsChars); + Normalize (mc, ref param_type_name, Report); + Type param_type = FindDocumentedType (mc, param_type_name, ds, cref, Report); + if (param_type == null) { Report.Warning (1580, 1, mc.Location, "Invalid type for parameter `{0}' in XML comment cref attribute `{1}'", (i + 1).ToString (), cref); return; } - plist.Add (paramType); + plist.Add (param_type); } - parameterTypes = plist.ToArray (typeof (Type)) as Type []; + parameter_types = plist.ToArray (); } - Type type = FindDocumentedType (mc, name, ds, cref); + Type type = FindDocumentedType (mc, name, ds, cref, Report); if (type != null // delegate must not be referenced with args - && (!type.IsSubclassOf (typeof (System.Delegate)) - || parameterTypes.Length == 0)) { - string result = type.FullName.Replace ("+", ".") - + (bracePos < 0 ? String.Empty : signature.Substring (bracePos)); + && (!TypeManager.IsDelegateType (type) + || parameter_types == null)) { + string result = GetSignatureForDoc (type) + + (brace_pos < 0 ? String.Empty : signature.Substring (brace_pos)); xref.SetAttribute ("cref", "T:" + result); return; // a type } - // don't use identifier here. System[] is not alloed. - if (RootNamespace.Global.IsNamespace (name)) { - xref.SetAttribute ("cref", "N:" + name); - return; // a namespace - } - int period = name.LastIndexOf ('.'); if (period > 0) { string typeName = name.Substring (0, period); - string memberName = name.Substring (period + 1); - Normalize (mc, ref memberName); - type = FindDocumentedType (mc, typeName, ds, cref); - int warnResult; + string member_name = name.Substring (period + 1); + Normalize (mc, ref member_name, Report); + type = FindDocumentedType (mc, typeName, ds, cref, Report); + int warn_result; if (type != null) { - MemberInfo mi = FindDocumentedMember (mc, type, memberName, parameterTypes, ds, out warnResult, cref, true, name); - if (warnResult > 0) + FoundMember fm = FindDocumentedMember (mc, type, member_name, parameter_types, ds, out warn_result, cref, true, name, Report); + if (warn_result > 0) return; - if (mi != null) { - xref.SetAttribute ("cref", GetMemberDocHead (mi.MemberType) + type.FullName.Replace ("+", ".") + "." + memberName + GetParametersFormatted (mi)); + if (!fm.IsEmpty) { + MemberInfo mi = fm.Member; + // we cannot use 'type' directly + // to get its name, since mi + // could be from DeclaringType + // for nested types. + xref.SetAttribute ("cref", GetMemberDocHead (mi.MemberType) + GetSignatureForDoc (fm.Type) + "." + member_name + GetParametersFormatted (mi)); return; // a member of a type } } } else { - int warnResult; - MemberInfo mi = FindDocumentedMember (mc, ds.TypeBuilder, name, parameterTypes, ds, out warnResult, cref, true, name); - if (warnResult > 0) + int warn_result; + FoundMember fm = FindDocumentedMember (mc, ds.TypeBuilder, name, parameter_types, ds, out warn_result, cref, true, name, Report); + if (warn_result > 0) return; - if (mi != null) { - xref.SetAttribute ("cref", GetMemberDocHead (mi.MemberType) + ds.TypeBuilder.FullName.Replace ("+", ".") + "." + name + GetParametersFormatted (mi)); + if (!fm.IsEmpty) { + MemberInfo mi = fm.Member; + // we cannot use 'type' directly + // to get its name, since mi + // could be from DeclaringType + // for nested types. + xref.SetAttribute ("cref", GetMemberDocHead (mi.MemberType) + GetSignatureForDoc (fm.Type) + "." + name + GetParametersFormatted (mi)); return; // local member name } } + // It still might be part of namespace name. + Namespace ns = ds.NamespaceEntry.NS.GetNamespace (name, false); + if (ns != null) { + xref.SetAttribute ("cref", "N:" + ns.GetSignatureForError ()); + return; // a namespace + } + if (GlobalRootNamespace.Instance.IsNamespace (name)) { + xref.SetAttribute ("cref", "N:" + name); + return; // a namespace + } + Report.Warning (1574, 1, mc.Location, "XML comment on `{0}' has cref attribute `{1}' that could not be resolved", mc.GetSignatureForError (), cref); @@ -716,31 +729,31 @@ namespace Mono.CSharp { static string GetParametersFormatted (MemberInfo mi) { MethodBase mb = mi as MethodBase; - bool isSetter = false; + bool is_setter = false; PropertyInfo pi = mi as PropertyInfo; if (pi != null) { mb = pi.GetGetMethod (); if (mb == null) { - isSetter = true; + is_setter = true; mb = pi.GetSetMethod (); } } if (mb == null) return String.Empty; - ParameterData parameters = TypeManager.GetParameterData (mb); + AParametersCollection parameters = TypeManager.GetParameterData (mb); if (parameters == null || parameters.Count == 0) return String.Empty; StringBuilder sb = new StringBuilder (); sb.Append ('('); for (int i = 0; i < parameters.Count; i++) { - if (isSetter && i + 1 == parameters.Count) + if (is_setter && i + 1 == parameters.Count) break; // skip "value". if (i > 0) sb.Append (','); - Type t = parameters.ParameterType (i); - sb.Append (t.FullName.Replace ('+', '.').Replace ('&', '@')); + Type t = parameters.Types [i]; + sb.Append (GetSignatureForDoc (t)); } sb.Append (')'); return sb.ToString (); @@ -760,11 +773,11 @@ namespace Mono.CSharp { return identifier; } - static void Report419 (MemberCore mc, string memberName, MemberInfo [] mis) + static void Report419 (MemberCore mc, string member_name, MemberInfo [] mis, Report Report) { Report.Warning (419, 3, mc.Location, "Ambiguous reference in cref attribute `{0}'. Assuming `{1}' but other overloads including `{2}' have also matched", - memberName, + member_name, TypeManager.GetFullNameSignature (mis [0]), TypeManager.GetFullNameSignature (mis [1])); } @@ -798,41 +811,64 @@ namespace Mono.CSharp { // Returns a string that represents the signature for this // member which should be used in XML documentation. // - public static string GetMethodDocCommentName (MethodCore mc, DeclSpace ds) + public static string GetMethodDocCommentName (MemberCore mc, ParametersCompiled parameters, DeclSpace ds) { - Parameter [] plist = mc.Parameters.FixedParameters; - Parameter parr = mc.Parameters.ArrayParameter; + IParameterData [] plist = parameters.FixedParameters; string paramSpec = String.Empty; if (plist != null) { StringBuilder psb = new StringBuilder (); + int i = 0; foreach (Parameter p in plist) { psb.Append (psb.Length != 0 ? "," : "("); - psb.Append (p.ExternalType ().FullName.Replace ("+", ".").Replace ('&', '@')); + psb.Append (GetSignatureForDoc (parameters.Types [i++])); + if ((p.ModFlags & Parameter.Modifier.ISBYREF) != 0) + psb.Append ('@'); } paramSpec = psb.ToString (); } - if (parr != null) - paramSpec += String.Concat ( - paramSpec == String.Empty ? "(" : ",", - parr.ParameterType.FullName.Replace ("+", ".")); if (paramSpec.Length > 0) paramSpec += ")"; string name = mc is Constructor ? "#ctor" : mc.Name; + if (mc.MemberName.IsGeneric) + name += "``" + mc.MemberName.CountTypeArguments; + string suffix = String.Empty; Operator op = mc as Operator; if (op != null) { switch (op.OperatorType) { case Operator.OpType.Implicit: case Operator.OpType.Explicit: - suffix = "~" + op.OperatorMethodBuilder.ReturnType.FullName.Replace ('+', '.'); + suffix = "~" + GetSignatureForDoc (op.MethodBuilder.ReturnType); break; } } return String.Concat (mc.DocCommentHeader, ds.Name, ".", name, paramSpec, suffix); } + static string GetSignatureForDoc (Type type) + { + if (TypeManager.IsGenericParameter (type)) + return (type.DeclaringMethod != null ? "``" : "`") + TypeManager.GenericParameterPosition (type); + + if (TypeManager.IsGenericType (type)) { + string g = type.Namespace; + if (g != null && g.Length > 0) + g += '.'; + int idx = type.Name.LastIndexOf ('`'); + g += (idx < 0 ? type.Name : type.Name.Substring (0, idx)) + '{'; + int argpos = 0; + foreach (Type t in type.GetGenericArguments ()) + g += (argpos++ > 0 ? "," : String.Empty) + GetSignatureForDoc (t); + g += '}'; + return g; + } + + string name = type.FullName != null ? type.FullName : type.Name; + return name.Replace ("+", ".").Replace ('&', '@'); + } + // // Raised (and passed an XmlElement that contains the comment) // when GenerateDocComment is writing documentation expectedly. @@ -841,33 +877,30 @@ namespace Mono.CSharp { // that means removal of DOM use. // internal static void OnMethodGenerateDocComment ( - MethodCore mc, DeclSpace ds, XmlElement el) + MethodCore mc, XmlElement el, Report Report) { - Hashtable paramTags = new Hashtable (); + var paramTags = new Dictionary (); foreach (XmlElement pelem in el.SelectNodes ("param")) { - int i; string xname = pelem.GetAttribute ("name"); - if (xname == "") + if (xname.Length == 0) continue; // really? but MS looks doing so - if (xname != "" && mc.Parameters.GetParameterByName (xname, out i) == null) + if (xname != "" && mc.Parameters.GetParameterIndexByName (xname) < 0) Report.Warning (1572, 2, mc.Location, "XML comment on `{0}' has a param tag for `{1}', but there is no parameter by that name", mc.GetSignatureForError (), xname); - else if (paramTags [xname] != null) + else if (paramTags.ContainsKey (xname)) Report.Warning (1571, 2, mc.Location, "XML comment on `{0}' has a duplicate param tag for `{1}'", mc.GetSignatureForError (), xname); paramTags [xname] = xname; } - Parameter [] plist = mc.Parameters.FixedParameters; - if (plist != null) { - foreach (Parameter p in plist) { - if (paramTags.Count > 0 && paramTags [p.Name] == null) - Report.Warning (1573, 4, mc.Location, "Parameter `{0}' has no matching param tag in the XML comment for `{1}'", - p.Name, mc.GetSignatureForError ()); - } + IParameterData [] plist = mc.Parameters.FixedParameters; + foreach (Parameter p in plist) { + if (paramTags.Count > 0 && !paramTags.ContainsKey (p.Name)) + Report.Warning (1573, 4, mc.Location, "Parameter `{0}' has no matching param tag in the XML comment for `{1}'", + p.Name, mc.GetSignatureForError ()); } } - private static void Normalize (MemberCore mc, ref string name) + private static void Normalize (MemberCore mc, ref string name, Report Report) { if (name.Length > 0 && name [0] == '@') name = name.Substring (1); @@ -930,19 +963,12 @@ namespace Mono.CSharp { // Stores XmlDocuments that are included in XML documentation. // Keys are included filenames, values are XmlDocuments. // - public Hashtable StoredDocuments = new Hashtable (); - - // - // Stores comments on partial types (should handle uniquely). - // Keys are PartialContainers, values are comment strings - // (didn't use StringBuilder; usually we have just 2 or more). - // - public IDictionary PartialComments = new ListDictionary (); + public Dictionary StoredDocuments = new Dictionary (); // // Outputs XML documentation comment from tokenized comments. // - public bool OutputDocComment (string asmfilename) + public bool OutputDocComment (string asmfilename, Report Report) { XmlTextWriter w = null; try { @@ -958,7 +984,7 @@ namespace Mono.CSharp { w.WriteEndElement (); // assembly w.WriteStartElement ("members"); XmlCommentOutput = w; - GenerateDocComment (); + GenerateDocComment (Report); w.WriteFullEndElement (); // members w.WriteEndElement (); w.WriteWhitespace (Environment.NewLine); @@ -976,46 +1002,17 @@ namespace Mono.CSharp { // // Fixes full type name of each documented types/members up. // - public void GenerateDocComment () + public void GenerateDocComment (Report r) { - TypeContainer root = RootContext.Tree.Types; - if (root.Interfaces != null) - foreach (Interface i in root.Interfaces) - DocUtil.GenerateTypeDocComment (i, null); + TypeContainer root = RootContext.ToplevelTypes; if (root.Types != null) foreach (TypeContainer tc in root.Types) - DocUtil.GenerateTypeDocComment (tc, null); - - if (root.Parts != null) { - IDictionary comments = PartialComments; - foreach (ClassPart cp in root.Parts) { - if (cp.DocComment == null) - continue; - comments [cp] = cp; - } - } + DocUtil.GenerateTypeDocComment (tc, null, r); if (root.Delegates != null) foreach (Delegate d in root.Delegates) - DocUtil.GenerateDocComment (d, null); - - if (root.Enums != null) - foreach (Enum e in root.Enums) - e.GenerateDocComment (null); - - IDictionary table = new ListDictionary (); - foreach (ClassPart cp in PartialComments.Keys) { - // FIXME: IDictionary does not guarantee that the keys will be - // accessed in the order they were added. - table [cp.PartialContainer] += cp.DocComment; - } - foreach (PartialContainer pc in table.Keys) { - pc.DocComment = table [pc] as string; - DocUtil.GenerateDocComment (pc, null); - } + DocUtil.GenerateDocComment (d, null, r); } } } - -#endif