.\" .\" mdoc-update manual page. .\" (C) 2008 Jonathan Pryor .\" Author: .\" Jonathan Pryor (jpryor@novell.com) .\" .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .TH "mdoc-update" 1 .SH NAME mdoc update \- \fBmdoc\fR(5) documentation format support .SH SYNOPSIS \fBmdoc update\fR [OPTIONS]* ASSEMBLIES .SH DESCRIPTION \fBmdoc update\fR is responsible for the following: .TP .B * Creating documentation stubs based on \fIASSEMBLIES\fR. The stub-creation process will create new \fBmdoc\fR(5) XML files for each type within \fIASSEMBLIES\fR, and provide documentation stubs for each member of those types. .TP .B * Update documentation stubs based on \fIASSEMBLIES\fR. Existing \fBmdoc\fR(5) documentation can be updated to reflect changes within \fIASSEMBLIES\fR, such 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. .PP \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 .TP .B \-\-delete Allow \fBmdoc update\fR to delete members from documentation files. The only members deleted are members which are no longer present within \fIASSEMBLIES\fR and are not present in any other assembly versions. .Sp If a type is no longer present, the documentation file is \fInot\fR deleted, but is instead \fIrenamed\fR to have a \fB.remove \fR extension. .Sp Version detection is done with the \fI//AssemblyVersion\fR elements; if there 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\-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 mdoc(1), mdoc(5), mdoc-assemble(1), mdoc-export-html(1), mdoc-validate(1), .SH MAILING LISTS .TP Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details. .SH WEB SITE Visit http://www.mono-project.com for details