X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=blobdiff_plain;f=man%2Fmdoc-update.1;h=d05091922195be609bc87cfa9b480e6341c83f90;hb=3a63a287b6e22d6f127895e2a81b6d3600daed9a;hp=92388a2a965030c44955e1eb5dc98afc7a391db2;hpb=f33941ae443d3b8116e7e2438c89aeef8e0aef31;p=mono.git diff --git a/man/mdoc-update.1 b/man/mdoc-update.1 index 92388a2a965..d0509192219 100644 --- a/man/mdoc-update.1 +++ b/man/mdoc-update.1 @@ -29,11 +29,9 @@ as added types and members, while preserving existing documentation. .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 @@ -51,15 +49,156 @@ are no \fI//AssemblyVersion\fR elements for a given \fI\fR or \fI\fR, then the \fI\fR will be renamed and/or the \fI\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 elements for members + added during the current program execution. + This keeps mdoc-update from re-generating + elements for all members (and thus + prevents re-insertion for members that had the + 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 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\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