+2008-12-04 Jonathan Pryor <jpryor@novell.com>
+
+ * Makefile: Specify --exceptions=all in mdoc-update invocations.
+ * exceptions.cs: Add support for documenting a *subset* of all
+ possible exceptions. Subsets include: the member itself, the member
+ and methods it calls that are in the same assembly, and all possible
+ methods across all assemblies.
+ * monodocer.cs: Allow --exceptions to take a SOURCES argument, to
+ control which location sources will be searched for exceptions.
+
2008-12-02 Jonathan Pryor <jpryor@novell.com>
* Makefile: Add --exceptions to `mdoc update` invocations to test
check-monodocer-update: mdoc.exe
find Test/en.expected -name \*.xml -exec rm "{}" \;
$(MAKE) Test/DocTest.dll-v1
- $(MONO) mdoc.exe update --exceptions -o Test/en.expected Test/DocTest.dll
+ $(MONO) mdoc.exe update --exceptions=all -o Test/en.expected Test/DocTest.dll
check-monodocer: mdoc.exe
-rm -Rf Test/en.actual
$(MAKE) Test/DocTest.dll-v1
- $(MONO) mdoc.exe update --exceptions -o Test/en.actual Test/DocTest.dll
+ $(MONO) mdoc.exe update --exceptions=all -o Test/en.actual Test/DocTest.dll
diff --exclude=.svn -rup Test/en.expected Test/en.actual
- $(MONO) mdoc.exe update --exceptions -o Test/en.actual Test/DocTest.dll
+ $(MONO) mdoc.exe update --exceptions=all -o Test/en.actual Test/DocTest.dll
diff --exclude=.svn -rup Test/en.expected Test/en.actual
check-monodocer-since-update: mdoc.exe
find Test/en.expected.since -name \*.xml -exec rm "{}" \;
$(MAKE) Test/DocTest.dll-v1
- $(MONO) mdoc.exe update --exceptions -o Test/en.expected.since Test/DocTest.dll
+ $(MONO) mdoc.exe update --exceptions=all -o Test/en.expected.since Test/DocTest.dll
$(MAKE) Test/DocTest.dll-v2
- $(MONO) mdoc.exe update --exceptions --since="Version 2.0" \
+ $(MONO) mdoc.exe update --exceptions=all --since="Version 2.0" \
-o Test/en.expected.since Test/DocTest.dll
check-monodocer-since: mdoc.exe
rm -Rf Test/en.actual
$(MAKE) Test/DocTest.dll-v1
- $(MONO) mdoc.exe update --exceptions -o Test/en.actual Test/DocTest.dll
+ $(MONO) mdoc.exe update --exceptions=all -o Test/en.actual Test/DocTest.dll
$(MAKE) Test/DocTest.dll-v2
- $(MONO) mdoc.exe update --exceptions --since="Version 2.0" \
+ $(MONO) mdoc.exe update --exceptions=all --since="Version 2.0" \
-o Test/en.actual Test/DocTest.dll
diff --exclude=.svn -rup Test/en.expected.since Test/en.actual
check-monodocer-importslashdoc-update: mdoc.exe
find Test/en.expected.importslashdoc -name \*.xml -exec rm "{}" \;
$(MAKE) Test/DocTest.dll-v1 TEST_CSCFLAGS=-doc:Test/DocTest.xml
- $(MONO) mdoc.exe update --exceptions -i Test/DocTest.xml \
+ $(MONO) mdoc.exe update --exceptions=all -i Test/DocTest.xml \
-o Test/en.expected.importslashdoc Test/DocTest.dll
check-monodocer-importslashdoc: mdoc.exe
rm -Rf Test/en.actual
$(MAKE) Test/DocTest.dll-v1 TEST_CSCFLAGS=-doc:Test/DocTest.xml
- $(MONO) mdoc.exe update --exceptions -i Test/DocTest.xml \
+ $(MONO) mdoc.exe update --exceptions=all -i Test/DocTest.xml \
-o Test/en.actual Test/DocTest.dll
diff --exclude=.svn -rup Test/en.expected.importslashdoc Test/en.actual
check-monodocer-importecmadoc-update: mdoc.exe
find Test/en.expected.importecmadoc -name \*.xml -exec rm "{}" \;
$(MAKE) Test/DocTest.dll-v1
- $(MONO) mdoc.exe update --exceptions -i Test/TestEcmaDocs.xml \
+ $(MONO) mdoc.exe update --exceptions=all -i Test/TestEcmaDocs.xml \
'--type=System.Action`1' --type=System.AsyncCallback \
--type=System.Environment --type=System.Array \
-o Test/en.expected.importecmadoc Test/DocTest.dll
check-monodocer-importecmadoc: mdoc.exe
rm -Rf Test/en.actual
$(MAKE) Test/DocTest.dll-v1
- $(MONO) mdoc.exe update --exceptions -i Test/TestEcmaDocs.xml \
+ $(MONO) mdoc.exe update --exceptions=all -i Test/TestEcmaDocs.xml \
'--type=System.Action`1' --type=System.AsyncCallback \
--type=System.Environment --type=System.Array \
-o Test/en.actual Test/DocTest.dll
using Mono.Cecil.Cil;
namespace Mono.Documentation {
+
+ [Flags]
+ public enum ExceptionLocations {
+ Member = 0x0,
+ Assembly = 0x1,
+ DependentAssemblies = 0x2,
+ All = Assembly | DependentAssemblies
+ }
public class ExceptionSources {
internal ExceptionSources (TypeReference exception)
// where ExceptionSource.Exception == xdoc(TypeRef)
Dictionary<string, Dictionary<string, ExceptionSources>> db = new Dictionary<string, Dictionary<string, ExceptionSources>> ();
+ ExceptionLocations locations;
+
+ public ExceptionLookup (ExceptionLocations locations)
+ {
+ this.locations = locations;
+ }
+
public IEnumerable<ExceptionSources> this [IMemberReference member] {
get {
if (member == null)
{
for (int i = 0; i < body.Instructions.Count; ++i) {
Instruction instruction = body.Instructions [i];
- Console.WriteLine ("#\topcode={0}; operand={1}", instruction.OpCode, instruction.Operand);
switch (instruction.OpCode.Code) {
case Code.Call:
case Code.Callvirt: {
- IEnumerable<ExceptionSources> memberExceptions = this [(IMemberReference) instruction.Operand];
- AddExceptions (body, instruction,
- memberExceptions.Select (es => es.Exception),
- memberExceptions.SelectMany (es => es.Sources),
- exceptions);
+ if ((locations & ExceptionLocations.Assembly) == 0 &&
+ (locations & ExceptionLocations.DependentAssemblies) == 0)
+ break;
+ IMemberReference memberRef = ((IMemberReference) instruction.Operand);
+ if (((locations & ExceptionLocations.Assembly) != 0 &&
+ body.Method.DeclaringType.Scope.Name == memberRef.DeclaringType.Scope.Name) ||
+ ((locations & ExceptionLocations.DependentAssemblies) != 0 &&
+ body.Method.DeclaringType.Scope.Name != memberRef.DeclaringType.Scope.Name)) {
+ IEnumerable<ExceptionSources> memberExceptions = this [memberRef];
+ AddExceptions (body, instruction,
+ memberExceptions.Select (es => es.Exception),
+ memberExceptions.SelectMany (es => es.Sources),
+ exceptions);
+ }
break;
}
case Code.Newobj: {
public bool pretty = true;
public string since;
public bool show_exceptions;
- public bool exceptions = false;
+ public ExceptionLocations? exceptions;
}
class MDocUpdater : MDocCommand
static bool nooverrides = true, delete = false, ignoremembers = false;
static bool pretty = false;
- static bool show_exceptions = false, exceptions = false;
+ static bool show_exceptions = false;
+ static ExceptionLocations? exceptions;
static int additions = 0, deletions = 0;
"Delete removed members from the XML files.",
v => opts.delete = v != null },
{ "since=",
- "Manually specify the assembly version that new members were added in.",
+ "Manually specify the assembly {VERSION} that new members were added in.",
v => opts.since = v },
{ "type=",
"Only update documentation for {TYPE}.",
v => opts.type.Add (v) },
- { "exceptions",
- "Document potential exceptions that members can generate.",
- v => opts.exceptions = v != null },
+ { "exceptions:",
+ "Document potential exceptions that members can generate. {SOURCES} " +
+ "is a comma-separated list of:\n" +
+ " asm Method calls in same assembly\n" +
+ " depasm Method calls in dependent assemblies\n" +
+ " all Record all possible exceptions\n" +
+ "If nothing is specified, then only exceptions from the member will " +
+ "be listed.",
+ v => opts.exceptions = ParseExceptionLocations (v) },
};
opts.assembly = Parse (p, args, "update",
"[OPTIONS]+ ASSEMBLIES",
opts.name = ""; // remove warning about unused member
}
+ static ExceptionLocations ParseExceptionLocations (string s)
+ {
+ ExceptionLocations loc = ExceptionLocations.Member;
+ if (s == null)
+ return loc;
+ foreach (var type in s.Split (',')) {
+ switch (type) {
+ case "asm": loc |= ExceptionLocations.Assembly; break;
+ case "depasm": loc |= ExceptionLocations.DependentAssemblies; break;
+ case "all": loc = ExceptionLocations.All; break;
+ default: throw new NotSupportedException ("Unsupported --exceptions value: " + type);
+ }
+ }
+ return loc;
+ }
+
static void Run (MDocUpdaterOptions opts)
{
nooverrides = !opts.overrides;
if (addremarks)
WriteElementInitialText(e, "remarks", "To be added.");
- if (exceptions && info.Member != null) {
+ if (exceptions.HasValue && info.Member != null) {
UpdateExceptions (e, info.Member);
}
private static void UpdateExceptions (XmlNode docs, IMemberReference member)
{
- foreach (var source in new ExceptionLookup ()[member]) {
+ foreach (var source in new ExceptionLookup (exceptions.Value)[member]) {
string cref = slashdocFormatter.GetDeclaration (source.Exception);
var node = docs.SelectSingleNode ("exception[@cref='" + cref + "']");
if (node != null)
projects / mono.git / commitdiff