[Mono-docs-list] Predefined docs patch
Martin Willemoes Hansen
mwh@sysrq.dk
Mon, 13 Oct 2003 15:32:44 +0200
--=-pGjIgsL2g8k/wtRpmDhQ
Content-Type: multipart/alternative; boundary="=-AIF1YZCWdTb6JNuWDmZZ"
--=-AIF1YZCWdTb6JNuWDmZZ
Content-Type: text/plain
Content-Transfer-Encoding: 7bit
Hi!
I was copying and pasting a lot when describing finalizers and the 3
internal constructors.
This patch will do the hard work in the updater.exe stage.
What do you think?
--
Martin Willemoes Hansen
--------------------------------------------------------
E-Mail mwh@sysrq.dk Website mwh.sysrq.dk
IRC MWH, freenode.net
--------------------------------------------------------
--=-AIF1YZCWdTb6JNuWDmZZ
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: 7bit
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 TRANSITIONAL//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=UTF-8">
<META NAME="GENERATOR" CONTENT="GtkHTML/3.0.9">
</HEAD>
<BODY>
Hi!<BR>
<BR>
I was copying and pasting a lot when describing finalizers and the 3 internal constructors.<BR>
This patch will do the hard work in the updater.exe stage.<BR>
<BR>
What do you think?<BR>
<TABLE CELLSPACING="0" CELLPADDING="0" WIDTH="100%">
<TR>
<TD>
<PRE>--
Martin Willemoes Hansen
--------------------------------------------------------
E-Mail mwh@sysrq.dk Website mwh.sysrq.dk
IRC MWH, freenode.net
--------------------------------------------------------
</PRE>
</TD>
</TR>
</TABLE>
</BODY>
</HTML>
--=-AIF1YZCWdTb6JNuWDmZZ--
--=-pGjIgsL2g8k/wtRpmDhQ
Content-Disposition: attachment; filename=PredefinedDocType.diff
Content-Type: text/x-patch; name=PredefinedDocType.diff; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
? PredefinedDocType.diff
Index: ChangeLog
===================================================================
RCS file: /cvs/public/monodoc/generator/ChangeLog,v
retrieving revision 1.21
diff -u -r1.21 ChangeLog
--- ChangeLog 22 Jul 2003 02:26:05 -0000 1.21
+++ ChangeLog 13 Oct 2003 13:10:06 -0000
@@ -1,3 +1,8 @@
+2003-10-13 Martin Willemoes Hansen <mwh@sysrq.dk>
+
+ * updater.cs: Added predefined documentation for finalizers and
+ internal ctor's.
+
2003-07-21 Duncan Mak <duncan@ximian.com>
* updater.cs: Fixed indentation from the previous commit and added
Index: updater.cs
===================================================================
RCS file: /cvs/public/monodoc/generator/updater.cs,v
retrieving revision 1.10
diff -u -r1.10 updater.cs
--- updater.cs 31 Jul 2003 04:59:42 -0000 1.10
+++ updater.cs 13 Oct 2003 13:10:06 -0000
@@ -821,8 +821,7 @@
XmlElement element = document.CreateElement (name);
if (text != null) {
- XmlText text_node = document.CreateTextNode (text);
- element.AppendChild (text_node);
+ element.InnerXml = text;
}
return element;
@@ -840,7 +839,7 @@
static XmlElement AddDocsNode (XmlDocument document, Type return_value, ParameterInfo [] pi)
{
XmlElement docs = document.CreateElement ("Docs");
- docs.AppendChild (AddElement (document, "summary", EmptyString));
+ docs.AppendChild (AddElement (document, "summary", GetSummary()));
if (pi != null)
foreach (ParameterInfo param in pi)
@@ -851,11 +850,34 @@
if (returns != null)
docs.AppendChild (returns);
- docs.AppendChild (AddElement (document, "remarks", EmptyString));
+ docs.AppendChild (AddElement (document, "remarks", GetRemarks()));
return docs;
}
+ static string predefined_doc_type = String.Empty;
+ static string GetSummary()
+ {
+ switch (predefined_doc_type) {
+ case "Finalize": return "Disposes the resources associated with the object.";
+ case "CtorGType": return "Internal constructor.";
+ case "CtorIntPtr": return "Internal constructor.";
+ case "CtorProtected": return "Internal constructor.";
+ default: return EmptyString;
+ }
+ }
+
+ static string GetRemarks()
+ {
+ switch (predefined_doc_type) {
+ case "Finalize": return String.Empty;
+ case "CtorGType": return "This is a constructor used by derivative types that would have their own <see cref=\"T:GLib.Type\" /> assigned to it. This is not typically used by C# code.";
+ case "CtorIntPtr": return "This is an internal constructor, and should not be used by user code.";
+ case "CtorProtected": return "This is an internal constructor, and should not be used by user code.";
+ default: return EmptyString;
+ }
+ }
+
static XmlElement AddDocsParamNode (XmlDocument document, ParameterInfo parameter)
{
Type param_type = parameter.ParameterType;
@@ -868,6 +890,12 @@
param.AppendChild (text_node);
param.AppendChild (see_node);
+ if (predefined_doc_type == "CtorGType") {
+ param.AppendChild (document.CreateTextNode (" for the this type."));
+ } else if (predefined_doc_type == "CtorIntPtr") {
+ param.AppendChild (document.CreateTextNode (" to the C object."));
+ }
+
return param;
}
@@ -888,7 +916,17 @@
XmlText text_node = document.CreateTextNode ("a ");
param.AppendChild (text_node);
param.AppendChild (see_node);
-
+
+ if (predefined_doc_type == "CtorGType") {
+ param.AppendChild (document.CreateTextNode (" created using the provided "));
+ see_node = document.CreateElement ("see");
+ see_node.SetAttribute ("cref", "T:GLib.Type");
+ param.AppendChild (see_node);
+ param.AppendChild (document.CreateTextNode ("."));
+ } else if (predefined_doc_type == "CtorIntPtr") {
+ param.AppendChild (document.CreateTextNode (" wrapping the C object."));
+ }
+
return param;
}
@@ -988,8 +1026,10 @@
ParameterInfo [] parameters = method.GetParameters ();
member.AppendChild (AddReturnValue (document, return_type));
- member.AppendChild (AddParameters (document, parameters));
- member.AppendChild (AddDocsNode (document, return_type, parameters));
+ member.AppendChild (AddParameters (document, parameters));
+ predefined_doc_type = method.Name;
+ member.AppendChild (AddDocsNode (document, return_type, parameters));
+ predefined_doc_type = String.Empty;
}
static void AddConstructor (XmlElement members, ConstructorInfo constructor)
@@ -1017,8 +1057,22 @@
// constructors have an empty ReturnValue node.
member.AppendChild (document.CreateElement ("ReturnValue"));
member.AppendChild (AddParameters (document, parameters));
+ predefined_doc_type = GetKnownCtorType (signature, constructor.DeclaringType.Name);
member.AppendChild (AddDocsNode (document, return_type, parameters));
+ predefined_doc_type = String.Empty;
}
+
+ static string GetKnownCtorType (string signature, string ctor_name)
+ {
+ if (signature == "protected " + ctor_name + " (GLib.Type gtype);")
+ return "CtorGType";
+ else if (signature == "public " + ctor_name + " (IntPtr raw);")
+ return "CtorIntPtr";
+ else if (signature == "protected " + ctor_name + " ();")
+ return "CtorProtected";
+ else
+ return String.Empty;
+ }
static void AddProperty (XmlElement members, PropertyInfo property)
{
--=-pGjIgsL2g8k/wtRpmDhQ--