Re: Proposing a new documentation subsystem

Jonathan Pryor <[email protected]> Sun, 25 Nov 2007 22:05:44 -0500

Newsgroups	gmane.comp.gnome.mono.documentation
Message-ID	<[email protected]>

On Sun, 2007-11-25 at 09:28 -0500, Jonathan Pryor wrote:
> The monodocer part should be a fairly minor change, probably < 100 LOC.
> (Probably < 20.)  The browser part will be somewhat more involved,
> mostly as it deals with XSLT, but I don't think it will be terribly
> difficult either.
> 
> Sadly, I'm not sure when I'll get a chance to work on this.  Hopefully
> before year-end.

Attached is a preliminary patch to add this support.  The monodocer
change is 66 lines, and generates output like the attached
Environment.xml.  monodocs2html has also been updated; Environment.html
is the current output.

I should stress that this is a work-in-progress; in particular, it
should (but doesn't) "garbage-collect" the <AssemblyVersion/> elements,
such that if updated assembly 2.0, and a member has an
<AssemblyVersion>2.0</AssemblyVersion> element AND the element has been
REMOVED, the docs are not currently updated to remove this element.
Similar things should be done to ONLY remove a member if e.g. there are
no remaining <AssemblyVersion/> elements (which would likely obsolete
the -ignore_extra_docs parameter if done well).

 - Jon

_______________________________________________
Mono-docs-list maillist  -  [email protected]
http://lists.ximian.com/mailman/listinfo/mono-docs-list

assembly-versions.diff (text/x-patch, 3 KB)

Index: monodocer.cs
===================================================================
--- monodocer.cs	(revision 90275)
+++ monodocer.cs	(working copy)
@@ -96,7 +96,7 @@
 		[Option("The {name} of the project this documentation is for.")]
 		public string name;
 
-		[Option("An XML documemntation {file} made by the /doc option of mcs/csc the contents of which will be imported.")]
+		[Option("An XML documentation {file} made by the /doc option of mcs/csc the contents of which will be imported.")]
 		public string importslashdoc;
 		
 		[Option("An ECMA or monodoc-generated XML documemntation {file} to import.")]
@@ -1213,7 +1213,7 @@
 		
 		XmlElement ass = WriteElement(root, "AssemblyInfo");
 		WriteElementText(ass, "AssemblyName", type.Assembly.GetName().Name);
-		WriteElementText(ass, "AssemblyVersion", type.Assembly.GetName().Version.ToString());
+		UpdateAssemblyVersions(ass, type, true);
 		if (type.Assembly.GetName().CultureInfo.Name != "")
 			WriteElementText(ass, "AssemblyCulture", type.Assembly.GetName().CultureInfo.Name);
 		else
@@ -1376,6 +1376,7 @@
 
 		WriteElementText(me, "MemberType", GetMemberType(mi));
 		
+		UpdateAssemblyVersions(me, mi, true);
 		MakeAttributes(me, mi, false);
 		MakeReturnValue(me, mi);
 		MakeParameters(me, mi);
@@ -1747,6 +1748,35 @@
 				n.ParentNode.RemoveChild(n);
 	}
 	
+	private static void UpdateAssemblyVersions(XmlElement root, MemberInfo member, bool add)
+	{
+		XmlElement e = (XmlElement) root.SelectSingleNode ("AssemblyVersions");
+		if (e == null) {
+			e = root.OwnerDocument.CreateElement("AssemblyVersions");
+			root.AppendChild(e);
+		}
+		Type type = member as Type;
+		if (type == null)
+			type = member.DeclaringType;
+		string assemblyVersion = type.Assembly.GetName().Version.ToString();
+		XmlElement c = null;
+		foreach (XmlElement version in e.SelectNodes("AssemblyVersion")) {
+			if (version.InnerText == assemblyVersion) {
+				c = version;
+			}
+		}
+		// c != null && add: ignore -- already present
+		if (c != null && !add) {
+			e.RemoveChild(c);
+		}
+		else if (c == null && add) {
+			c = root.OwnerDocument.CreateElement("AssemblyVersion");
+			c.InnerText = assemblyVersion;
+			e.AppendChild(c);
+		}
+		// c == null && !add: ignore -- already not present
+	}
+
 	private static void MakeAttributes(XmlElement root, object attributes, bool assemblyAttributes) {
 		int len;
 #if NET_1_0
Index: stylesheet.xsl
===================================================================
--- stylesheet.xsl	(revision 90275)
+++ stylesheet.xsl	(working copy)
@@ -463,6 +463,19 @@
 
 				<xsl:call-template name="DisplayDocsInformation"/>
 
+				<xsl:if test="count(AssemblyVersions/AssemblyVersion) &gt; 0">
+					<h4 class="Subsection">Requires Assembly Versions:</h4>
+					<ul>
+					<xsl:for-each select="AssemblyVersions/AssemblyVersion">
+						<li>
+							<xsl:value-of select="/Type/AssemblyInfo/AssemblyName"/> 
+							<xsl:value-of select="' '"/>
+							<xsl:value-of select="."/>
+						</li>
+					</xsl:for-each>
+					</ul>
+				</xsl:if>
+
 				<hr size="1"/>
 					
 				</div>

Environment.xml (application/xml, 1.2 KB)

<Type Name="Environment" FullName="System.Environment">
  <TypeSignature Language="C#" Value="public static class Environment" />
  <AssemblyInfo>
    <AssemblyName>DocTest</AssemblyName>
    <AssemblyVersions>
      <AssemblyVersion>0.0.0.0</AssemblyVersion>
    </AssemblyVersions>
  </AssemblyInfo>
  <Base>
    <BaseTypeName>System.Object</BaseTypeName>
  </Base>
  <Interfaces />
  <Docs>
    <summary>To be added.</summary>
    <remarks>To be added.</remarks>
  </Docs>
  <Members>
    <Member MemberName="GetFolderPath">
      <MemberSignature Language="C#" Value="public static string GetFolderPath (Environment.SpecialFolder folder);" />
      <MemberType>Method</MemberType>
      <AssemblyVersions>
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
      </AssemblyVersions>
      <ReturnValue>
        <ReturnType>System.String</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="folder" Type="System.Environment+SpecialFolder" />
      </Parameters>
      <Docs>
        <param name="folder">To be added.</param>
        <summary>To be added.</summary>
        <returns>To be added.</returns>
        <remarks>To be added.</remarks>
      </Docs>
    </Member>
  </Members>
</Type>

Environment.html (application/x-mozilla-bookmarks, 4.4 KB) - not displayed