man/mdoc-update.1

   1 .\"
   2 .\" mdoc-update manual page.
   3 .\" (C) 2008 Jonathan Pryor
   4 .\" Author:
   5 .\"   Jonathan Pryor (jpryor@novell.com)
   6 .\"
   7 .de Sp \" Vertical space (when we can't use .PP)
   8 .if t .sp .5v
   9 .if n .sp
  10 ..
  11 .TH "mdoc-update" 1
  12 .SH NAME
  13 mdoc update \- \fBmdoc\fR(5) documentation format support
  14 .SH SYNOPSIS
  15 \fBmdoc update\fR [OPTIONS]* ASSEMBLIES
  16 .SH DESCRIPTION
  17 \fBmdoc update\fR is responsible for the following:
  18 .TP
  19 .B *
  20 Creating documentation stubs based on \fIASSEMBLIES\fR.  The stub-creation
  21 process will create new \fBmdoc\fR(5) XML files for each type within
  22 \fIASSEMBLIES\fR, and provide documentation stubs for each member of those
  23 types.
  24 .TP
  25 .B *
  26 Update documentation stubs based on \fIASSEMBLIES\fR.  Existing \fBmdoc\fR(5)
  27 documentation can be updated to reflect changes within \fIASSEMBLIES\fR, such
  28 as added types and members, while preserving existing documentation.
  29 .Sp
  30 In some limited circumstances, renames will be tracked, minimizing the
  31 documentation burden when e.g. a parameter is renamed.
  32 .PP
  33 \fBmdoc update\fR does not rely on documentation found within source code,
  34 though it can import XML Documentation Comments via the \fB\-i\fR option.
  35 .PP
  36 See \fBmdoc\fR(1) and \fBmdoc\fR(5) for more information.
  37 .SH OPTIONS
  38 .TP
  39 .B \-\-delete
  40 Allow \fBmdoc update\fR to delete members from documentation files.
  41 The only members deleted are members which are no longer present within
  42 \fIASSEMBLIES\fR and are not present in any other assembly versions.
  43 .Sp
  44 If a type is no longer present, the documentation file is \fInot\fR
  45 deleted, but is instead \fIrenamed\fR to have a \fB.remove \fR extension.
  46 .Sp
  47 Version detection is done with the \fI//AssemblyVersion\fR elements; if there
  48 are no \fI//AssemblyVersion\fR elements for a given \fI<Type>\fR or
  49 \fI<Member/>\fR, then the \fI<Type>\fR will be renamed and/or the
  50 \fI<Member/>\fR will be removed.
  51 .TP
  52 \fB\-\-exceptions\fR[=\fISOURCES\fR]
  53 EXPERIMENTAL.  This is not 100% reliable, but is intended to serve as an aid
  54 for documentation writers.
  55 .Sp
  56 Inspect member bodies to determine what exceptions can be generated from the
  57 member.
  58 .Sp
  59 \fISOURCES\fR is an optional comma-separated list of the following sources
  60 that should be searched for exceptions:
  61 .Sp
  62 .nf
  63         added   Only generate <exception/> elements for members
  64                   added during the current program execution.
  65                   This keeps mdoc-update from re-generating
  66                   <exception/> elements for all members (and thus
  67                   prevents re-insertion for members that had the
  68                   <exception/> elements removed).
  69         all     Find exceptions created in the member itself,
  70                   references to members in the same assembly,
  71                   and references to members in dependent
  72                   assemblies.
  73         asm     Find exceptions created in the member itself and
  74                   references to members within the same assembly
  75                   as the member.
  76         depasm  Find exceptions created in the member itself and
  77                   references to members within dependent
  78                   assemblies.
  79 .fi
  80 .Sp
  81 If \fISOURCES\fR isn't provided (the default), then only exceptions created
  82 within the member itself will be documented.
  83 .Sp
  84 LIMITATIONS: Exception searching is currently implemented by looking for the
  85 exception types that are explicitly created based on the known compile-time
  86 types.  This has the following limitations:
  87 .RS
  88 .ne 8
  89 .TP
  90 .B *
  91 This will not find exceptions which are implicit to the IL, such as
  92 NullReferenceException and IndexOutOfRangeException.
  93 .TP
  94 .B *
  95 This will find exceptions which are \fInot\fR thrown, e.g.
  96 .nf
  97
  98     public void CreateAnException ()
  99     {
 100         Exception e = new Exception ();
 101     }
 102
 103 .fi
 104 .TP
 105 .B *
 106 This will not "follow" delegate and interface calls:
 107 .nf
 108
 109     public void UsesDelegates ()
 110     {
 111         Func<int, int> a = x => {throw new Exception ();};
 112         a (4);
 113     }
 114
 115 .fi
 116 The function \fIUsesDelegates()\fR won't have any exceptions documented.
 117 .TP
 118 .B *
 119 This will find exceptions which "cannot happen", such as
 120 ArgumentNullExceptions for arguments which are "known" to be non-null:
 121 .nf
 122
 123     public void A ()
 124     {
 125         B ("this parameter isn't null");
 126     }
 127
 128     public void B (string s)
 129     {
 130         if (s == null)
 131             throw new ArgumentNullException ("s");
 132     }
 133
 134 .fi
 135 For the above, if \fB--exceptions=asm\fR is provided then \fIA()\fR will be
 136 documented as throwing an ArgumentNullException, which cannot happen.
 137 .ne
 138 .RE
 139 .TP
 140 \fB\-f\fR=\fIFLAG\fR
 141 Specify a flag to alter behavior.  Valid flags include:
 142 .RS
 143 .ne 8
 144 .TP
 145 .B no-assembly-versions
 146 See the \fB-fno-assembly-versions\fR documentation, below.
 147 .ne
 148 .RE
 149 .TP
 150 \fB\-fno-assembly-versions\fR
 151 Do not generate \fI/Type/AssemblyInfo/AssemblyVersion\fR and
 152 \fI/Type/Members/Member/AssemblyInfo\fR elements.
 153 .Sp
 154 This is useful to prevent "churn" during updates.  Normally, if a type or
 155 member hasn't changed but the assembly version has changed, then all types and
 156 members will be updated to include a new \fI//AssemblyVersion\fR element, thus
 157 increasing the amount of changes that need review before committing (assuming
 158 all changes are actually reviewed before commit).
 159 .Sp
 160 WARNING: This \fIwill\fR interact badly with the \fB--delete\fR option, as
 161 \fB--delete\fR uses the \fI//AssemblyVersion\fR elements to track version
 162 changes.  Thus, if you have a member which is present in an early assembly
 163 version and is removed in a subsequent assembly version, such as
 164 \fISystem.Text.UTF8Encoding.GetBytes(string)\fR (which is present in .NET 1.0
 165 but not in .NET 2.0), then the member will be removed when the
 166 \fB--delete -fno-assembly-versions\fR options are specified, the member was
 167 present in an earlier version of the assembly, and the current version of the
 168 assembly does not contain the member.
 169 .Sp
 170 Consequently, this option should \fIonly\fR be specified if types and members
 171 will \fInever\fR be removed from an assembly.
 172 .TP
 173 \fB\-i\fR, \fB\-\-import\fR=\fIFILE\fR
 174 Import documentation found within \fIFILE\fR.
 175 .Sp
 176 \fIFILE\fR may contain either \fIcsc /doc\fR XML or \fIECMA-335\fR XML.
 177 .TP
 178 \fB\-L\fR, \fB\-\-lib\fR=\fIDIRECTORY\fR
 179 Add \fIDIRECTORY\fR to the assembly search path, so that dependencies of
 180 \fIASSEMBLIES\fR can be found without documenting those assemblies.
 181 .TP
 182 \fB\-o\fR, \fB\-\-out\fR=\fIDIRECTORY\fR
 183 Place the generated stubs into \fIDIRECTORY\fR.
 184 .Sp
 185 When updating documentation, \fIDIRECTORY\fR is also the source directory.
 186 .TP
 187 \fB\-r\fR=\fIASSEMBLY\fR
 188 \fIASSEMBLY\fR is a dependency for one of \fIASSEMBLIES\fR which should
 189 \fInot\fR be documented but is required to process one of \fIASSEMBLIES\fR.
 190 Add the directory containing \fIASSEMBLY\fR to the assembly search path.
 191 .Sp
 192 This option is equivalent to specifying \fB\-L\fR `\fIdirname\fR ASSEMBLY`.
 193 .TP
 194 \fB\-\-since\fR=\fIVERSION\fR
 195 When \fIupdating\fR documentation for an assembly, if a type or member is
 196 encountered which didn't exist in the previous version of the assembly a
 197 \fB<since version="\fR\fIVERSION\fR\fB"/>\fR element will be inserted.
 198 .TP
 199 \fB\-\-type\fR=\fITYPE\fR
 200 Only update documentation for the type \fITYPE\fR.
 201 .TP
 202 .B \-h, \-?, \-\-help
 203 Display a help message and exit.
 204 .SH SEE ALSO
 205 mdoc(1),
 206 mdoc(5),
 207 mdoc-assemble(1),
 208 mdoc-export-html(1),
 209 mdoc-validate(1),
 210 .SH MAILING LISTS
 211 .TP
 212 Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
 213 .SH WEB SITE
 214 Visit http://www.mono-project.com for details