// (C) 2004 Novell, Inc.
//
//
-
#if ! BOOTSTRAP_WITH_OLDLIB
using System;
using System.Collections;
//
// Support class for XML documentation.
//
+#if NET_2_0
+ static
+#else
+ abstract
+#endif
public class DocUtil
{
+#if !NET_2_0
+ private DocUtil () {}
+#endif
// TypeContainer
//
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);
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;
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,
// 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;
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);
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;
}
//
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)
}
private static MemberInfo [] FilterOverridenMembersOut (
- Type type, MemberInfo [] ml)
+ MemberInfo [] ml)
{
if (ml == null)
return empty_member_infos;
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))
// delegate must not be referenced with args
&& (!type.IsSubclassOf (typeof (System.Delegate))
|| parameterTypes == null)) {
- string result = type.FullName.Replace ("+", ".")
+ 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);
// to get its name, since mi
// could be from DeclaringType
// for nested types.
- xref.SetAttribute ("cref", GetMemberDocHead (mi.MemberType) + fm.Type.FullName.Replace ("+", ".") + "." + memberName + GetParametersFormatted (mi));
+ xref.SetAttribute ("cref", GetMemberDocHead (mi.MemberType) + GetSignatureForDoc (fm.Type) + "." + memberName + GetParametersFormatted (mi));
return; // a member of a type
}
}
// to get its name, since mi
// could be from DeclaringType
// for nested types.
- xref.SetAttribute ("cref", GetMemberDocHead (mi.MemberType) + fm.Type.FullName.Replace ("+", ".") + "." + name + GetParametersFormatted (mi));
+ 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);
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 ();
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 ();
}
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.
// 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",
//
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.
//
//
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);
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);
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