lineHead, split, 0, j);
return el;
} catch (XmlException ex) {
- Report.Warning (1570, 1, mc.Location, "XML comment on '{0}' has non-well-formed XML ({1}).", name, ex.Message);
+ 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;
}
n.WriteTo (RootContext.Documentation.XmlCommentOutput);
}
- else if (mc.IsExposedFromAssembly (ds) &&
- // There are no warnings when the container also
- // misses documentations.
- (ds == null || ds.DocComment != null))
- {
- Report.Warning (1591, 4, mc.Location,
- "Missing XML comment for publicly visible type or member '{0}'", mc.GetSignatureForError ());
+ else if (mc.IsExposedFromAssembly (ds)) {
+ Constructor c = mc as Constructor;
+ if (c == null || !c.IsDefault ())
+ Report.Warning (1591, 4, mc.Location,
+ "Missing XML comment for publicly visible type or member `{0}'", mc.GetSignatureForError ());
}
}
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.");
+ Report.Warning (1590, 1, mc.Location, "Invalid XML `include' element. Missing `file' attribute");
el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" Include tag is invalid "), el);
}
else if (path == "") {
- Report.Warning (1590, 1, mc.Location, "Invalid XML 'include' element; Missing 'path' attribute.");
+ Report.Warning (1590, 1, mc.Location, "Invalid XML `include' element. Missing `path' attribute");
el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" Include tag is invalid "), el);
}
else {
doc.Load (file);
RootContext.Documentation.StoredDocuments.Add (file, doc);
} catch (Exception) {
- el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (String.Format (" Badly formed XML in at comment file '{0}': cannot be included ", file)), el);
- Report.Warning (1592, 1, mc.Location, "Badly formed XML in included comments file -- '{0}'", file);
+ el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (String.Format (" Badly formed XML in at comment file `{0}': cannot be included ", file)), el);
+ Report.Warning (1592, 1, mc.Location, "Badly formed XML in included comments file -- `{0}'", file);
}
}
bool keepIncludeNode = false;
el.ParentNode.InsertBefore (el.OwnerDocument.ImportNode (n, true), el);
} catch (Exception ex) {
el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" Failed to insert some or all of included XML "), el);
- Report.Warning (1589, 1, mc.Location, "Unable to include XML fragment '{0}' of file {1} -- {2}.", path, file, ex.Message);
+ Report.Warning (1589, 1, mc.Location, "Unable to include XML fragment `{0}' of file `{1}' ({2})", path, file, ex.Message);
}
}
if (!keepIncludeNode)
// 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, bool allowAlias)
+ private static Type FindDocumentedType (MemberCore mc, string name, DeclSpace ds, string cref)
{
bool isArray = false;
string identifier = name;
isArray = true;
}
}
- Type t = FindDocumentedTypeNonArray (mc, identifier,
- ds, allowAlias);
+ Type t = FindDocumentedTypeNonArray (mc, identifier, ds, cref);
if (t != null && isArray)
t = Array.CreateInstance (t, 0).GetType ();
return t;
}
- private static Type FindDocumentedTypeNonArray (MemberCore mc,
- string identifier, DeclSpace ds, bool allowAlias)
+ private static Type FindDocumentedTypeNonArray (MemberCore mc,
+ string identifier, DeclSpace ds, string cref)
{
switch (identifier) {
case "int":
case "void":
return typeof (void);
}
- if (allowAlias) {
- IAlias alias = ds.LookupAlias (identifier);
- if (alias != null)
- identifier = alias.Name;
- }
- Type t = ds.FindType (mc.Location, identifier);
- if (t == null)
- t = TypeManager.LookupTypeDirect (identifier);
- return t;
+ FullNamedExpression e = ds.LookupType (identifier, mc.Location, false);
+ if (e != null) {
+ if (!(e is TypeExpr))
+ return null;
+ return ((TypeExpr) e).Type;
+ }
+ int index = identifier.LastIndexOf ('.');
+ if (index < 0)
+ return null;
+ int warn;
+ Type parent = FindDocumentedType (mc, identifier.Substring (0, index), ds, cref);
+ if (parent == null)
+ return null;
+ // no need to detect warning 419 here
+ return FindDocumentedMember (mc, parent,
+ identifier.Substring (index + 1),
+ emptyParamList,
+ ds, out warn, cref) as Type;
}
//
BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance,
MethodSignature.method_signature_filter,
msig);
- if (mis.Length > 0)
+ if (mis.Length > 0) {
+ if (IsAmbiguous (mis))
+ warningType = 419;
return mis [0];
+ }
if (paramList.Length == 0) {
// search for fields/events etc.
BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static | BindingFlags.Instance,
Type.FilterName,
memberName);
- return (mis.Length > 0) ? mis [0] : null;
+ if (mis.Length == 0)
+ return null;
+ if (IsAmbiguous (mis))
+ warningType = 419;
+ return mis [0];
}
// search for operators (whose parameters exactly
default:
warningType = 1584;
Report.Warning (1020, 1, mc.Location, "Overloadable {0} operator is expected", paramList.Length == 2 ? "binary" : "unary");
- Report.Warning (1584, 1, mc.Location, "XML comment on '{0}' has syntactically incorrect attribute '{1}'", mc.GetSignatureForError (), cref);
+ Report.Warning (1584, 1, mc.Location, "XML comment on `{0}' has syntactically incorrect cref attribute `{1}'",
+ mc.GetSignatureForError (), cref);
return null;
}
}
- // here we still does not consider return type (to
+ // here we still don't consider return type (to
// detect CS1581 or CS1002+CS1584).
msig = new MethodSignature (oper, null, paramList);
mis = type.FindMembers (
((PropertyInfo) mi).PropertyType :
null;
if (returnTypeName != null) {
- Type returnType = FindDocumentedType (mc, returnTypeName, ds, true);
+ Type returnType = FindDocumentedType (mc, returnTypeName, ds, cref);
if (returnType == null || returnType != expected) {
warningType = 1581;
- Report.Warning (1581, 1, mc.Location, "Invalid return type in XML comment cref attribute '{0}'", cref);
+ Report.Warning (1581, 1, mc.Location, "Invalid return type in XML comment cref attribute `{0}'", cref);
return null;
}
}
return mis [0];
}
+ private static bool IsAmbiguous (MemberInfo [] members)
+ {
+ if (members.Length < 2)
+ return false;
+ if (members.Length > 2)
+ return true;
+ if (members [0] is EventInfo && members [1] is FieldInfo)
+ return false;
+ if (members [1] is EventInfo && members [0] is FieldInfo)
+ return false;
+ return true;
+ }
+
private static Type [] emptyParamList = new Type [0];
//
name = signature;
parameters = String.Empty;
}
+ Normalize (mc, ref name);
string identifier = name;
// Check if identifier is valid.
// This check is not necessary to mark as error, but
// csc specially reports CS1584 for wrong identifiers.
- foreach (string nameElem in identifier.Split ('.')) {
+ string [] nameElems = identifier.Split ('.');
+ for (int i = 0; i < nameElems.Length; i++) {
+ string nameElem = nameElems [i];
+ if (nameElem.EndsWith ("[]"))
+ nameElem = nameElem.Substring (
+ nameElem.Length - 2);
+ if (i > 0)
+ Normalize (mc, ref nameElem);
if (!Tokenizer.IsValidIdentifier (nameElem)
&& nameElem.IndexOf ("operator") < 0) {
- if (nameElem.EndsWith ("[]") &&
- Tokenizer.IsValidIdentifier (
- nameElem.Substring (
- 0, nameElem.Length - 2)))
- continue;
-
- Report.Warning (1584, 1, mc.Location, "XML comment on '{0}' has syntactically incorrect attribute '{1}'", mc.GetSignatureForError (), cref);
+ Report.Warning (1584, 1, mc.Location, "XML comment on `{0}' has syntactically incorrect cref attribute `{1}'",
+ mc.GetSignatureForError (), cref);
xref.SetAttribute ("cref", "!:" + signature);
return;
}
ArrayList plist = new ArrayList ();
for (int i = 0; i < paramList.Length; i++) {
string paramTypeName = paramList [i].Trim (wsChars);
- Type paramType = FindDocumentedType (mc, paramTypeName, ds, true);
+ Normalize (mc, ref paramTypeName);
+ Type paramType = FindDocumentedType (mc, paramTypeName, ds, cref);
if (paramType == null) {
- Report.Warning (1580, 1, mc.Location, "Invalid type for parameter '{0}' in XML comment cref attribute '{1}'", i + 1, cref);
+ Report.Warning (1580, 1, mc.Location, "Invalid type for parameter `{0}' in XML comment cref attribute `{1}'", i + 1, cref);
return;
}
plist.Add (paramType);
parameters = sb.ToString ();
}
- Type type = FindDocumentedType (mc, name, ds, true);
- if (type != null) {
+ Type type = FindDocumentedType (mc, name, ds, cref);
+ if (type != null
+ // delegate must not be referenced with args
+ && (!type.IsSubclassOf (typeof (System.Delegate))
+ || parameterTypes.Length == 0)) {
xref.SetAttribute ("cref", "T:" + type.FullName.Replace ("+", "."));
return; // a type
}
// don't use identifier here. System[] is not alloed.
- if (Namespace.IsNamespace (name)) {
+ if (RootNamespace.Global.IsNamespace (name)) {
xref.SetAttribute ("cref", "N:" + name);
return; // a namespace
}
if (period > 0) {
string typeName = name.Substring (0, period);
string memberName = name.Substring (period + 1);
- type = FindDocumentedType (mc, typeName, ds, false);
+ Normalize (mc, ref memberName);
+ type = FindDocumentedType (mc, typeName, ds, cref);
int warnResult;
if (type != null) {
MemberInfo mi = FindDocumentedMember (mc, type, memberName, parameterTypes, ds, out warnResult, cref);
- if (warnResult > 0)
+ if (warnResult == 419)
+ Report419 (mc, name, mi);
+ else if (warnResult > 0)
return;
if (mi != null) {
xref.SetAttribute ("cref", GetMemberDocHead (mi.MemberType) + type.FullName.Replace ("+", ".") + "." + memberName + parameters);
else {
int warnResult;
MemberInfo mi = FindDocumentedMember (mc, ds.TypeBuilder, name, parameterTypes, ds, out warnResult, cref);
- if (warnResult > 0)
+ if (warnResult == 419)
+ Report419 (mc, name, mi);
+ else if (warnResult > 0)
return;
if (mi != null) {
xref.SetAttribute ("cref", GetMemberDocHead (mi.MemberType) + ds.TypeBuilder.FullName.Replace ("+", ".") + "." + name);
}
}
- 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 ());
+ Report.Warning (1574, 1, mc.Location, "XML comment on `{0}' has cref attribute `{1}' that could not be resolved",
+ mc.GetSignatureForError (), cref);
xref.SetAttribute ("cref", "!:" + name);
}
+ static void Report419 (MemberCore mc, string memberName, MemberInfo mi)
+ {
+ Report.Warning (419, 3, mc.Location,
+ "Ambiguous reference in cref attribute `{0}'. Assuming `{1}' but other overloads including `{1}' have also matched",
+ memberName, TypeManager.GetFullNameSignature (mi));
+ }
+
//
// Get a prefix from member type for XML documentation (used
// to formalize cref target name).
if (xname == "")
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 such parameter.", mc.Name, xname);
+ 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)
- Report.Warning (1571, 2, mc.Location, "XML comment on '{0}' has a duplicate param tag for '{1}'", mc.Name, 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}' (but other parameters do)", mc.Name, 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 ());
}
}
}
- // Enum
- public static void GenerateEnumDocComment (Enum e, DeclSpace ds)
+ private static void Normalize (MemberCore mc, ref string name)
+ {
+ if (name.Length > 0 && name [0] == '@')
+ name = name.Substring (1);
+ else if (Tokenizer.IsKeyword (name) && !IsTypeName (name))
+ Report.Warning (1041, 1, mc.Location, "Identifier expected. `{0}' is a keyword", name);
+ }
+
+ private static bool IsTypeName (string name)
{
- GenerateDocComment (e, ds);
- foreach (string name in e.ordered_enums) {
- MemberCore mc = e.GetDefinition (name);
- GenerateDocComment (mc, e);
+ switch (name) {
+ case "bool":
+ case "byte":
+ case "char":
+ case "decimal":
+ case "double":
+ case "float":
+ case "int":
+ case "long":
+ case "object":
+ case "sbyte":
+ case "short":
+ case "string":
+ case "uint":
+ case "ulong":
+ case "ushort":
+ case "void":
+ return true;
}
+ return false;
}
}
w.WriteEndDocument ();
return true;
} catch (Exception ex) {
- Report.Error (1569, "Error generating XML documentation file '{0}' ('{1}')", docfilename, ex.Message);
+ Report.Error (1569, "Error generating XML documentation file `{0}' (`{1}')", docfilename, ex.Message);
return false;
} finally {
if (w != null)
if (root.Enums != null)
foreach (Enum e in root.Enums)
- DocUtil.GenerateEnumDocComment (e, null);
+ 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) {
projects / mono.git / blobdiff