.Sp
In some limited circumstances, renames will be tracked, minimizing the
documentation burden when e.g. a parameter is renamed.
-circumstances,
-creates stubs and updates documentation in the \fBmdoc\fR(5)
-documentation format from \fIASSEMBLIES\fR.
.PP
-\fBmdoc update\fR does not rely on documentation found within source code.
+\fBmdoc update\fR does not rely on documentation found within source code,
+though it can import XML Documentation Comments via the \fB\-i\fR option.
.PP
See \fBmdoc\fR(1) and \fBmdoc\fR(5) for more information.
.SH OPTIONS
\fI<Member/>\fR, then the \fI<Type>\fR will be renamed and/or the
\fI<Member/>\fR will be removed.
.TP
+\fB\-\-exceptions\fR[=\fISOURCES\fR]
+EXPERIMENTAL. This is not 100% reliable, but is intended to serve as an aid
+for documentation writers.
+.Sp
+Inspect member bodies to determine what exceptions can be generated from the
+member.
+.Sp
+\fISOURCES\fR is an optional comma-separated list of the following sources
+that should be searched for exceptions:
+.Sp
+.nf
+ added Only generate <exception/> elements for members
+ added during the current program execution.
+ This keeps mdoc-update from re-generating
+ <exception/> elements for all members (and thus
+ prevents re-insertion for members that had the
+ <exception/> elements removed).
+ all Find exceptions created in the member itself,
+ references to members in the same assembly,
+ and references to members in dependent
+ assemblies.
+ asm Find exceptions created in the member itself and
+ references to members within the same assembly
+ as the member.
+ depasm Find exceptions created in the member itself and
+ references to members within dependent
+ assemblies.
+.fi
+.Sp
+If \fISOURCES\fR isn't provided (the default), then only exceptions created
+within the member itself will be documented.
+.Sp
+LIMITATIONS: Exception searching is currently implemented by looking for the
+exception types that are explicitly created based on the known compile-time
+types. This has the following limitations:
+.RS
+.ne 8
+.TP
+.B *
+This will not find exceptions which are implicit to the IL, such as
+NullReferenceException and IndexOutOfRangeException.
+.TP
+.B *
+This will find exceptions which are \fInot\fR thrown, e.g.
+.nf
+
+ public void CreateAnException ()
+ {
+ Exception e = new Exception ();
+ }
+
+.fi
+.TP
+.B *
+This will not "follow" delegate and interface calls:
+.nf
+
+ public void UsesDelegates ()
+ {
+ Func<int, int> a = x => {throw new Exception ();};
+ a (4);
+ }
+
+.fi
+The function \fIUsesDelegates()\fR won't have any exceptions documented.
+.TP
+.B *
+This will find exceptions which "cannot happen", such as
+ArgumentNullExceptions for arguments which are "known" to be non-null:
+.nf
+
+ public void A ()
+ {
+ B ("this parameter isn't null");
+ }
+
+ public void B (string s)
+ {
+ if (s == null)
+ throw new ArgumentNullException ("s");
+ }
+
+.fi
+For the above, if \fB--exceptions=asm\fR is provided then \fIA()\fR will be
+documented as throwing an ArgumentNullException, which cannot happen.
+.ne
+.RE
+.TP
+\fB\-f\fR=\fIFLAG\fR
+Specify a flag to alter behavior. Valid flags include:
+.RS
+.ne 8
+.TP
+.B no-assembly-versions
+See the \fB-fno-assembly-versions\fR documentation, below.
+.ne
+.RE
+.TP
+\fB\-fno-assembly-versions\fR
+Do not generate \fI/Type/AssemblyInfo/AssemblyVersion\fR and
+\fI/Type/Members/Member/AssemblyInfo\fR elements.
+.Sp
+This is useful to prevent "churn" during updates. Normally, if a type or
+member hasn't changed but the assembly version has changed, then all types and
+members will be updated to include a new \fI//AssemblyVersion\fR element, thus
+increasing the amount of changes that need review before committing (assuming
+all changes are actually reviewed before commit).
+.Sp
+WARNING: This \fIwill\fR interact badly with the \fB--delete\fR option, as
+\fB--delete\fR uses the \fI//AssemblyVersion\fR elements to track version
+changes. Thus, if you have a member which is present in an early assembly
+version and is removed in a subsequent assembly version, such as
+\fISystem.Text.UTF8Encoding.GetBytes(string)\fR (which is present in .NET 1.0
+but not in .NET 2.0), then the member will be removed when the
+\fB--delete -fno-assembly-versions\fR options are specified, the member was
+present in an earlier version of the assembly, and the current version of the
+assembly does not contain the member.
+.Sp
+Consequently, this option should \fIonly\fR be specified if types and members
+will \fInever\fR be removed from an assembly.
+.TP
\fB\-i\fR, \fB\-\-import\fR=\fIFILE\fR
Import documentation found within \fIFILE\fR.
.Sp
\fIFILE\fR may contain either \fIcsc /doc\fR XML or \fIECMA-335\fR XML.
.TP
-\fB\-o\fR, \fB\-\-out\fB=\fIDIRECTORY\fR
+\fB\-L\fR, \fB\-\-lib\fR=\fIDIRECTORY\fR
+Add \fIDIRECTORY\fR to the assembly search path, so that dependencies of
+\fIASSEMBLIES\fR can be found without documenting those assemblies.
+.TP
+\fB\-o\fR, \fB\-\-out\fR=\fIDIRECTORY\fR
Place the generated stubs into \fIDIRECTORY\fR.
.Sp
When updating documentation, \fIDIRECTORY\fR is also the source directory.
+.TP
+\fB\-r\fR=\fIASSEMBLY\fR
+\fIASSEMBLY\fR is a dependency for one of \fIASSEMBLIES\fR which should
+\fInot\fR be documented but is required to process one of \fIASSEMBLIES\fR.
+Add the directory containing \fIASSEMBLY\fR to the assembly search path.
+.Sp
+This option is equivalent to specifying \fB\-L\fR `\fIdirname\fR ASSEMBLY`.
+.TP
+\fB\-\-since\fR=\fIVERSION\fR
+When \fIupdating\fR documentation for an assembly, if a type or member is
+encountered which didn't exist in the previous version of the assembly a
+\fB<since version="\fR\fIVERSION\fR\fB"/>\fR element will be inserted.
+.TP
+\fB\-\-type\fR=\fITYPE\fR
+Only update documentation for the type \fITYPE\fR.
+.TP
.B \-h, \-?, \-\-help
Display a help message and exit.
.SH SEE ALSO
projects / mono.git / blobdiff