Skip to content

Commit bae230f

Browse files
rofrrofr
committed
add api-doc generation from xml comments
1 parent d11e089 commit bae230f

File tree

6 files changed

+260
-14
lines changed

6 files changed

+260
-14
lines changed

‎Documentation.xsl

+214
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- ================================================================================ -->
3+
<!-- Amend, distribute, spindle and mutilate as desired, but don't remove this header -->
4+
<!-- A simple XML Documentation to basic HTML transformation stylesheet -->
5+
<!-- (c)2005 by Emma Burrows -->
6+
<!-- ================================================================================ -->
7+
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
8+
9+
<!-- DOCUMENT TEMPLATE -->
10+
<!-- Format the whole document as a valid HTML document -->
11+
<xsl:template match="/">
12+
<HTML>
13+
<BODY>
14+
<xsl:apply-templates select="//assembly"/>
15+
</BODY>
16+
</HTML>
17+
</xsl:template>
18+
19+
<!-- ASSEMBLY TEMPLATE -->
20+
<!-- For each Assembly, display its name and then its member types -->
21+
<xsl:template match="assembly">
22+
<H1><xsl:value-of select="name"/></H1>
23+
<xsl:apply-templates select="//member[contains(@name,'T:')]"/>
24+
</xsl:template>
25+
26+
<!-- TYPE TEMPLATE -->
27+
<!-- Loop through member types and display their properties and methods -->
28+
<xsl:template match="//member[contains(@name,'T:')]">
29+
30+
<!-- Two variables to make code easier to read -->
31+
<!-- A variable for the name of this type -->
32+
<xsl:variable name="MemberName"
33+
select="substring-after(@name, '.')"/>
34+
35+
<!-- Get the type's fully qualified name without the T: prefix -->
36+
<xsl:variable name="FullMemberName"
37+
select="substring-after(@name, ':')"/>
38+
39+
<!-- Display the type's name and information -->
40+
<H2><xsl:value-of select="$MemberName"/></H2>
41+
<xsl:apply-templates/>
42+
43+
<!-- If this type has public fields, display them -->
44+
<xsl:if test="//member[contains(@name,concat('F:',$FullMemberName))]">
45+
<H3>Fields</H3>
46+
47+
<xsl:for-each select="//member[contains(@name,concat('F:',$FullMemberName))]">
48+
<H4><xsl:value-of select="substring-after(@name, concat('F:',$FullMemberName,'.'))"/></H4>
49+
<xsl:apply-templates/>
50+
</xsl:for-each>
51+
</xsl:if>
52+
53+
<!-- If this type has properties, display them -->
54+
<xsl:if test="//member[contains(@name,concat('P:',$FullMemberName))]">
55+
<H3>Properties</H3>
56+
57+
<xsl:for-each select="//member[contains(@name,concat('P:',$FullMemberName))]">
58+
<H4><xsl:value-of select="substring-after(@name, concat('P:',$FullMemberName,'.'))"/></H4>
59+
<xsl:apply-templates/>
60+
</xsl:for-each>
61+
</xsl:if>
62+
63+
<!-- If this type has methods, display them -->
64+
<xsl:if test="//member[contains(@name,concat('M:',$FullMemberName))]">
65+
<H3>Methods</H3>
66+
67+
<xsl:for-each select="//member[contains(@name,concat('M:',$FullMemberName))]">
68+
69+
<!-- If this is a constructor, display the type name
70+
(instead of "#ctor"), or display the method name -->
71+
<H4>
72+
<xsl:choose>
73+
<xsl:when test="contains(@name, '#ctor')">
74+
Constructor:
75+
<xsl:value-of select="$MemberName"/>
76+
<xsl:value-of select="substring-after(@name, '#ctor')"/>
77+
</xsl:when>
78+
<xsl:otherwise>
79+
<xsl:value-of select="substring-after(@name, concat('M:',$FullMemberName,'.'))"/>
80+
</xsl:otherwise>
81+
</xsl:choose>
82+
</H4>
83+
84+
<xsl:apply-templates select="summary"/>
85+
86+
<!-- Display parameters if there are any -->
87+
<xsl:if test="count(param)!=0">
88+
<H5>Parameters</H5>
89+
<xsl:apply-templates select="param"/>
90+
</xsl:if>
91+
92+
<!-- Display return value if there are any -->
93+
<xsl:if test="count(returns)!=0">
94+
<H5>Return Value</H5>
95+
<xsl:apply-templates select="returns"/>
96+
</xsl:if>
97+
98+
<!-- Display exceptions if there are any -->
99+
<xsl:if test="count(exception)!=0">
100+
<H5>Exceptions</H5>
101+
<xsl:apply-templates select="exception"/>
102+
</xsl:if>
103+
104+
<!-- Display examples if there are any -->
105+
<xsl:if test="count(example)!=0">
106+
<H5>Example</H5>
107+
<xsl:apply-templates select="example"/>
108+
</xsl:if>
109+
110+
</xsl:for-each>
111+
112+
</xsl:if>
113+
</xsl:template>
114+
115+
<!-- OTHER TEMPLATES -->
116+
<!-- Templates for other tags -->
117+
<xsl:template match="c">
118+
<CODE><xsl:apply-templates /></CODE>
119+
</xsl:template>
120+
121+
<xsl:template match="code">
122+
<PRE><xsl:apply-templates /></PRE>
123+
</xsl:template>
124+
125+
<xsl:template match="example">
126+
<P><STRONG>Example: </STRONG><xsl:apply-templates /></P>
127+
</xsl:template>
128+
129+
<xsl:template match="exception">
130+
<P><STRONG><xsl:value-of select="substring-after(@cref,'T:')"/>: </STRONG><xsl:apply-templates /></P>
131+
</xsl:template>
132+
133+
<xsl:template match="include">
134+
<A HREF="{@file}">External file</A>
135+
</xsl:template>
136+
137+
<xsl:template match="para">
138+
<P><xsl:apply-templates /></P>
139+
</xsl:template>
140+
141+
<xsl:template match="param">
142+
<P><STRONG><xsl:value-of select="@name"/>: </STRONG><xsl:apply-templates /></P>
143+
</xsl:template>
144+
145+
<xsl:template match="paramref">
146+
<EM><xsl:value-of select="@name" /></EM>
147+
</xsl:template>
148+
149+
<xsl:template match="permission">
150+
<P><STRONG>Permission: </STRONG><EM><xsl:value-of select="@cref" /> </EM><xsl:apply-templates /></P>
151+
</xsl:template>
152+
153+
<xsl:template match="remarks">
154+
<P><xsl:apply-templates /></P>
155+
</xsl:template>
156+
157+
<xsl:template match="returns">
158+
<P><STRONG>Return Value: </STRONG><xsl:apply-templates /></P>
159+
</xsl:template>
160+
161+
<xsl:template match="see">
162+
<EM>See: <xsl:value-of select="@cref" /></EM>
163+
</xsl:template>
164+
165+
<xsl:template match="seealso">
166+
<EM>See also: <xsl:value-of select="@cref" /></EM>
167+
</xsl:template>
168+
169+
<xsl:template match="summary">
170+
<P><xsl:apply-templates /></P>
171+
</xsl:template>
172+
173+
<xsl:template match="list">
174+
<xsl:choose>
175+
<xsl:when test="@type='bullet'">
176+
<UL>
177+
<xsl:for-each select="listheader">
178+
<LI><strong><xsl:value-of select="term"/>: </strong><xsl:value-of select="definition"/></LI>
179+
</xsl:for-each>
180+
<xsl:for-each select="list">
181+
<LI><strong><xsl:value-of select="term"/>: </strong><xsl:value-of select="definition"/></LI>
182+
</xsl:for-each>
183+
</UL>
184+
</xsl:when>
185+
<xsl:when test="@type='number'">
186+
<OL>
187+
<xsl:for-each select="listheader">
188+
<LI><strong><xsl:value-of select="term"/>: </strong><xsl:value-of select="definition"/></LI>
189+
</xsl:for-each>
190+
<xsl:for-each select="list">
191+
<LI><strong><xsl:value-of select="term"/>: </strong><xsl:value-of select="definition"/></LI>
192+
</xsl:for-each>
193+
</OL>
194+
</xsl:when>
195+
<xsl:when test="@type='table'">
196+
<TABLE>
197+
<xsl:for-each select="listheader">
198+
<TH>
199+
<TD><xsl:value-of select="term"/></TD>
200+
<TD><xsl:value-of select="definition"/></TD>
201+
</TH>
202+
</xsl:for-each>
203+
<xsl:for-each select="list">
204+
<TR>
205+
<TD><strong><xsl:value-of select="term"/>: </strong></TD>
206+
<TD><xsl:value-of select="definition"/></TD>
207+
</TR>
208+
</xsl:for-each>
209+
</TABLE>
210+
</xsl:when>
211+
</xsl:choose>
212+
</xsl:template>
213+
214+
</xsl:stylesheet>

‎build-api-docs.cmd

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
2+
tools\xslt Documentation.xsl src\OrigoDB.Core\bin\release\origodb.core.xml build\api-docs.html

‎build.cake

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
@echo off
2+
3+
:Build
4+
cls
5+
6+
if not exist tools\Cake\Cake.exe (
7+
echo Installing Cake...
8+
tools\nuget\nuget.exe install Cake -OutputDirectory tools -ExcludeVersion -NonInteractive
9+
echo.
10+
)
11+
12+
if not exist tools\NUnit.Runners\tools\nunit-console.exe (
13+
echo Installing NUnit runners...
14+
tools\nuget\nuget.exe install nunit.runners -OutputDirectory tools -ExcludeVersion -NonInteractive
15+
echo.
16+
)
17+
18+
SET BUILDMODE="Release"
19+
IF NOT [%1]==[] (set BUILDMODE="%1")
20+
21+
echo Starting Cake...
22+
"tools\Cake\Cake.exe" "build.csx" "-verbosity=verbose" "-config=%BUILDMODE%"
23+
24+
exit /b %errorlevel%

‎build.csx

+19-12
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
using System.Text.RegularExpressions;
2-
2+
33
var target = Argument("target", "Default");
44
var config = Argument("config", "Release");
55
var nunit = Argument("nunit", false);
@@ -16,16 +16,16 @@ Task("NuGetRestore")
1616
{
1717
NuGetRestore("./src/OrigoDB.sln");
1818
});
19-
19+
2020
Task("Build")
2121
.IsDependentOn("NuGetRestore")
2222
.Does(() =>
2323
{
24-
MSBuild("./src/OrigoDB.sln", settings =>
24+
MSBuild("./src/OrigoDB.sln", settings =>
2525
settings.SetConfiguration(config)
2626
.UseToolVersion(MSBuildToolVersion.VS2012)
2727
.WithTarget("clean")
28-
.WithTarget("build"));
28+
.WithTarget("build"));
2929
});
3030

3131
Task("NUnitTest")
@@ -53,27 +53,34 @@ Task("Zip")
5353
var root = "./build/";
5454
var outFile = "./build/OrigoDB.Core.binaries." + version + "-" + config + ".zip";
5555
var files = root + "/*";
56-
56+
5757
// Package the bin folder.
58-
Zip(root, outFile);
58+
Zip(root, outFile);
5959
});
60-
61-
60+
61+
6262
Task("NuGet")
6363
.IsDependentOn("Tests")
64-
.Does(() =>
64+
.Does(() =>
6565
{
6666
NuGetPack("./OrigoDB.Core.nuspec", new NuGetPackSettings {
6767
Version = version,
6868
Symbols = true
6969
});
7070
});
7171

72+
Task("ApiDocs")
73+
.IsDependentOn("Build")
74+
.Does(() => {
75+
XmlTransform("Documenation.xsl", @"bin\Release\OrigoDB.Core.XML", output + "/api-docs.html")
76+
})
77+
;
7278
Task("Default")
7379
.IsDependentOn("Zip")
7480
.IsDependentOn("NuGet")
75-
.IsDependentOn("Tests");
76-
81+
.IsDependentOn("Tests")
82+
.IsDependentOn("ApiDocs")
83+
7784
////////////////////////////////////////////////
7885

79-
RunTarget(target);
86+
RunTarget(target);

‎src/OrigoDB.Core/OrigoDB.Core.csproj

+1-2
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,7 @@
4141
<DefineConstants>TRACE</DefineConstants>
4242
<ErrorReport>prompt</ErrorReport>
4343
<WarningLevel>4</WarningLevel>
44-
<DocumentationFile>
45-
</DocumentationFile>
44+
<DocumentationFile>bin\Release\OrigoDB.Core.XML</DocumentationFile>
4645
<NoWarn>1591</NoWarn>
4746
<CodeAnalysisRuleSet>AllRules.ruleset</CodeAnalysisRuleSet>
4847
</PropertyGroup>

‎tools/xslt.exe

5.5 KB
Binary file not shown.

0 commit comments

Comments
 (0)