X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=blobdiff_plain;f=mcs%2Fmcs%2Fdoc.cs;h=90a9d1bb66f255d215ffcb3c66916412a5f54c0c;hb=e0df8328d11d79623c1b0369cf15544b26a18db0;hp=75af12994b2b753a2fa70faea608a792020503c7;hpb=c0ad1558af3c96b8d1eacc8535f3e0be0e43a3ed;p=mono.git diff --git a/mcs/mcs/doc.cs b/mcs/mcs/doc.cs index 75af12994b2..90a9d1bb66f 100644 --- a/mcs/mcs/doc.cs +++ b/mcs/mcs/doc.cs @@ -9,7 +9,6 @@ // (C) 2004 Novell, Inc. // // - #if ! BOOTSTRAP_WITH_OLDLIB using System; using System.Collections; @@ -31,8 +30,16 @@ namespace Mono.CSharp { // // Support class for XML documentation. // +#if NET_2_0 + static +#else + abstract +#endif public class DocUtil { +#if !NET_2_0 + private DocUtil () {} +#endif // TypeContainer // @@ -55,15 +62,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.Delegates != null) + foreach (Delegate de in t.Delegates) + de.GenerateDocComment (t); if (t.Enums != null) foreach (Enum en in t.Enums) en.GenerateDocComment (t); @@ -151,11 +152,19 @@ namespace Mono.CSharp { 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. + ArrayList al = new ArrayList (nl.Count); + foreach (XmlNode inc in nl) + al.Add (inc); + foreach (XmlElement inc in al) + if (!HandleInclude (mc, inc)) + inc.ParentNode.RemoveChild (inc); + } // FIXME: it could be done with XmlReader DeclSpace dsTarget = mc as DeclSpace; @@ -172,7 +181,7 @@ namespace Mono.CSharp { 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,17 +193,20 @@ 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) { + bool keepIncludeNode = 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); + keepIncludeNode = 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); + keepIncludeNode = true; } else { XmlDocument doc = RootContext.Documentation.StoredDocuments [file] as XmlDocument; @@ -208,7 +220,6 @@ 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); @@ -224,9 +235,8 @@ 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 keepIncludeNode; } // @@ -333,8 +343,7 @@ namespace Mono.CSharp { // 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).Member as Type; } private static MemberInfo [] empty_member_infos = @@ -352,7 +361,7 @@ namespace Mono.CSharp { 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) @@ -380,26 +389,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); 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) { @@ -430,34 +426,65 @@ namespace Mono.CSharp { return al.ToArray (typeof (MemberInfo)) as MemberInfo []; } + struct FoundMember + { + public static FoundMember Empty = new FoundMember (true); + + public bool IsEmpty; + public readonly MemberInfo Member; + public readonly Type Type; + + public FoundMember (bool regardlessOfThisValueItsEmpty) + { + IsEmpty = true; + Member = null; + Type = null; + } + + public FoundMember (Type foundType, MemberInfo member) + { + IsEmpty = false; + Type = foundType; + Member = member; + } + } + // // Returns a MemberInfo that is referenced in XML documentation // (by "see" or "seealso" elements). // - private static MemberInfo FindDocumentedMember (MemberCore mc, + private static FoundMember FindDocumentedMember (MemberCore mc, Type type, string memberName, Type [] paramList, DeclSpace ds, out int warningType, string cref, bool warn419, string nameForError) { + for (; type != null; type = type.DeclaringType) { + MemberInfo mi = FindDocumentedMemberNoNest ( + mc, type, memberName, paramList, ds, + out warningType, cref, warn419, + nameForError); + if (mi != null) + return new FoundMember (type, mi); + } warningType = 0; - MethodSignature msig = new MethodSignature (memberName, null, paramList); - MemberInfo [] mis = FindMethodBase (type, - BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance, - msig); + 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 memberName, + Type [] paramList, DeclSpace ds, out int warningType, + string cref, bool warn419, string nameForError) + { + warningType = 0; + MemberInfo [] mis; - if (paramList.Length == 0) { + if (paramList == 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); + mis = FilterOverridenMembersOut (mis); if (mis == null || mis.Length == 0) return null; if (warn419 && IsAmbiguous (mis)) @@ -465,6 +492,17 @@ namespace Mono.CSharp { return mis [0]; } + MethodSignature msig = new MethodSignature (memberName, null, paramList); + mis = FindMethodBase (type, + BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance, + msig); + + if (warn419 && mis.Length > 0) { + if (IsAmbiguous (mis)) + Report419 (mc, nameForError, mis); + return mis [0]; + } + // search for operators (whose parameters exactly // matches with the list) and possibly report CS1581. string oper = null; @@ -620,7 +658,7 @@ namespace Mono.CSharp { } else { name = signature; - parameters = String.Empty; + parameters = null; } Normalize (mc, ref name); @@ -644,8 +682,12 @@ namespace Mono.CSharp { } // check if parameters are valid - Type [] parameterTypes = Type.EmptyTypes; - if (parameters.Length > 0) { + Type [] parameterTypes; + if (parameters == null) + parameterTypes = null; + else if (parameters.Length == 0) + parameterTypes = Type.EmptyTypes; + else { string [] paramList = parameters.Split (','); ArrayList plist = new ArrayList (); for (int i = 0; i < paramList.Length; i++) { @@ -666,19 +708,13 @@ namespace Mono.CSharp { if (type != null // delegate must not be referenced with args && (!type.IsSubclassOf (typeof (System.Delegate)) - || parameterTypes.Length == 0)) { - string result = type.FullName.Replace ("+", ".") + || parameterTypes == null)) { + string result = GetSignatureForDoc (type) + (bracePos < 0 ? String.Empty : signature.Substring (bracePos)); 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); @@ -687,26 +723,47 @@ namespace Mono.CSharp { type = FindDocumentedType (mc, typeName, ds, cref); int warnResult; if (type != null) { - MemberInfo mi = FindDocumentedMember (mc, type, memberName, parameterTypes, ds, out warnResult, cref, true, name); + FoundMember fm = FindDocumentedMember (mc, type, memberName, parameterTypes, ds, out warnResult, cref, true, name); if (warnResult > 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) + "." + memberName + 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); + FoundMember fm = FindDocumentedMember (mc, ds.TypeBuilder, name, parameterTypes, ds, out warnResult, cref, true, name); if (warnResult > 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.FullName); + return; // a namespace + } + if (RootNamespace.Global.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); @@ -740,7 +797,7 @@ namespace Mono.CSharp { if (i > 0) sb.Append (','); Type t = parameters.ParameterType (i); - sb.Append (t.FullName.Replace ('+', '.').Replace ('&', '@')); + sb.Append (GetSignatureForDoc (t)); } sb.Append (')'); return sb.ToString (); @@ -801,20 +858,15 @@ namespace Mono.CSharp { public static string GetMethodDocCommentName (MethodCore mc, DeclSpace ds) { Parameter [] plist = mc.Parameters.FixedParameters; - Parameter parr = mc.Parameters.ArrayParameter; string paramSpec = String.Empty; if (plist != null) { StringBuilder psb = new StringBuilder (); foreach (Parameter p in plist) { psb.Append (psb.Length != 0 ? "," : "("); - psb.Append (p.ExternalType ().FullName.Replace ("+", ".").Replace ('&', '@')); + psb.Append (GetSignatureForDoc (p.ExternalType ())); } paramSpec = psb.ToString (); } - if (parr != null) - paramSpec += String.Concat ( - paramSpec == String.Empty ? "(" : ",", - parr.ParameterType.FullName.Replace ("+", ".")); if (paramSpec.Length > 0) paramSpec += ")"; @@ -826,13 +878,20 @@ namespace Mono.CSharp { 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) + { + return TypeManager.IsGenericParameter (type) ? + "`" + TypeManager.GenericParameterPosition (type) : + type.FullName.Replace ("+", ".").Replace ('&', '@'); + } + // // Raised (and passed an XmlElement that contains the comment) // when GenerateDocComment is writing documentation expectedly. @@ -841,13 +900,13 @@ namespace Mono.CSharp { // that means removal of DOM use. // internal static void OnMethodGenerateDocComment ( - MethodCore mc, DeclSpace ds, XmlElement el) + MethodCore mc, XmlElement el) { Hashtable paramTags = new Hashtable (); 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) Report.Warning (1572, 2, mc.Location, "XML comment on `{0}' has a param tag for `{1}', but there is no parameter by that name", @@ -858,12 +917,10 @@ namespace Mono.CSharp { 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 ()); - } + 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 ()); } } @@ -932,13 +989,6 @@ namespace Mono.CSharp { // 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 (); - // // Outputs XML documentation comment from tokenized comments. // @@ -978,7 +1028,7 @@ namespace Mono.CSharp { // public void GenerateDocComment () { - TypeContainer root = RootContext.Tree.Types; + TypeContainer root = RootContext.ToplevelTypes; if (root.Interfaces != null) foreach (Interface i in root.Interfaces) DocUtil.GenerateTypeDocComment (i, null); @@ -987,15 +1037,6 @@ namespace Mono.CSharp { 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; - } - } - if (root.Delegates != null) foreach (Delegate d in root.Delegates) DocUtil.GenerateDocComment (d, null); @@ -1004,18 +1045,7 @@ namespace Mono.CSharp { 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); - } } } } - #endif