1mdoc-update(1)              General Commands Manual             mdoc-update(1)
2
3
4

NAME

6       mdoc update - mdoc(5) documentation format support
7

SYNOPSIS

9       mdoc update [OPTIONS]* ASSEMBLIES
10

DESCRIPTION

12       mdoc update is responsible for the following:
13
14       *      Creating documentation stubs based on ASSEMBLIES.  The stub-cre‐
15              ation process will create new mdoc(5) XML files  for  each  type
16              within ASSEMBLIES, and provide documentation stubs for each mem‐
17              ber of those types.
18
19       *      Update  documentation  stubs  based  on  ASSEMBLIES.    Existing
20              mdoc(5)  documentation  can be updated to reflect changes within
21              ASSEMBLIES, such as added types and  members,  while  preserving
22              existing documentation.
23
24              In some limited circumstances, renames will be tracked, minimiz‐
25              ing the documentation burden when e.g. a parameter is renamed.
26
27       mdoc update does not rely on documentation found  within  source  code,
28       though it can import XML Documentation Comments via the -i option.
29
30       See mdoc(1) and mdoc(5) for more information.
31

OPTIONS

33       --delete
34              Allow  mdoc  update  to delete members from documentation files.
35              The only members deleted are members which are no longer present
36              within ASSEMBLIES and are not present in any other assembly ver‐
37              sions.
38
39              If a type is no longer present, the documentation  file  is  not
40              deleted, but is instead renamed to have a .remove  extension.
41
42              Version  detection  is done with the //AssemblyVersion elements;
43              if there are no //AssemblyVersion elements for a given <Type> or
44              <Member/>,  then the <Type> will be renamed and/or the <Member/>
45              will be removed.
46
47       --exceptions[=SOURCES]
48              EXPERIMENTAL.  This is not 100% reliable,  but  is  intended  to
49              serve as an aid for documentation writers.
50
51              Inspect member bodies to determine what exceptions can be gener‐
52              ated from the member.
53
54              SOURCES is an optional comma-separated  list  of  the  following
55              sources that should be searched for exceptions:
56
57                      added   Only generate <exception/> elements for members
58                                added during the current program execution.
59                                This keeps mdoc-update from re-generating
60                                <exception/> elements for all members (and thus
61                                prevents re-insertion for members that had the
62                                <exception/> elements removed).
63                      all     Find exceptions created in the member itself,
64                                references to members in the same assembly,
65                                and references to members in dependent
66                                assemblies.
67                      asm     Find exceptions created in the member itself and
68                                references to members within the same assembly
69                                as the member.
70                      depasm  Find exceptions created in the member itself and
71                                references to members within dependent
72                                assemblies.
73
74              If  SOURCES  isn't  provided (the default), then only exceptions
75              created within the member itself will be documented.
76
77              LIMITATIONS: Exception searching  is  currently  implemented  by
78              looking  for  the  exception  types  that are explicitly created
79              based on the known compile-time types.  This has  the  following
80              limitations:
81
82              *      This  will  not find exceptions which are implicit to the
83                     IL, such as NullReferenceException and IndexOutOfRangeEx‐
84                     ception.
85
86              *      This will find exceptions which are not thrown, e.g.
87
88                         public void CreateAnException ()
89                         {
90                             Exception e = new Exception ();
91                         }
92
93
94              *      This will not "follow" delegate and interface calls:
95
96                         public void UsesDelegates ()
97                         {
98                             Func<int, int> a = x => {throw new Exception ();};
99                             a (4);
100                         }
101
102                     The  function  UsesDelegates()  won't have any exceptions
103                     documented.
104
105              *      This will find exceptions which "cannot happen", such  as
106                     ArgumentNullExceptions for arguments which are "known" to
107                     be non-null:
108
109                         public void A ()
110                         {
111                             B ("this parameter isn't null");
112                         }
113
114                         public void B (string s)
115                         {
116                             if (s == null)
117                                 throw new ArgumentNullException ("s");
118                         }
119
120                     For the above, if --exceptions=asm is provided  then  A()
121                     will  be documented as throwing an ArgumentNullException,
122                     which cannot happen.
123
124       -f=FLAG
125              Specify a flag to alter behavior.  Valid flags include:
126
127              no-assembly-versions
128                     See the -fno-assembly-versions documentation, below.
129
130       -fno-assembly-versions
131              Do   not   generate    /Type/AssemblyInfo/AssemblyVersion    and
132              /Type/Members/Member/AssemblyInfo elements.
133
134              This  is useful to prevent "churn" during updates.  Normally, if
135              a type or member hasn't changed but  the  assembly  version  has
136              changed, then all types and members will be updated to include a
137              new //AssemblyVersion element, thus  increasing  the  amount  of
138              changes that need review before committing (assuming all changes
139              are actually reviewed before commit).
140
141              WARNING: This will interact badly with the --delete  option,  as
142              --delete  uses  the  //AssemblyVersion elements to track version
143              changes.  Thus, if you have a member  which  is  present  in  an
144              early  assembly  version and is removed in a subsequent assembly
145              version,   such   as   System.Text.UTF8Encoding.GetBytes(string)
146              (which  is  present  in  .NET 1.0 but not in .NET 2.0), then the
147              member will be removed when the --delete  -fno-assembly-versions
148              options are specified, the member was present in an earlier ver‐
149              sion of the assembly, and the current version  of  the  assembly
150              does not contain the member.
151
152              Consequently,  this option should only be specified if types and
153              members will never be removed from an assembly.
154
155       -i, --import=FILE
156              Import documentation found within FILE.
157
158              FILE may contain either csc /doc XML or ECMA-335 XML.
159
160       -L, --lib=DIRECTORY
161              Add DIRECTORY to the assembly search path, so that  dependencies
162              of ASSEMBLIES can be found without documenting those assemblies.
163
164       -o, --out=DIRECTORY
165              Place the generated stubs into DIRECTORY.
166
167              When updating documentation, DIRECTORY is also the source direc‐
168              tory.
169
170       -r=ASSEMBLY
171              ASSEMBLY is a dependency for one of ASSEMBLIES which should  not
172              be documented but is required to process one of ASSEMBLIES.  Add
173              the directory containing ASSEMBLY to the assembly search path.
174
175              This option is equivalent to specifying -L `dirname ASSEMBLY`.
176
177       --since=VERSION
178              When updating documentation for an assembly, if a type or member
179              is encountered which didn't exist in the previous version of the
180              assembly a <since version="VERSION"/> element will be inserted.
181
182       --type=TYPE
183              Only update documentation for the type TYPE.
184
185       -h, -?, --help
186              Display a help message and exit.
187

SEE ALSO

189       mdoc(1),  mdoc(5),  mdoc-assemble(1),  mdoc-export-html(1),  mdoc-vali‐
190       date(1),
191

MAILING LISTS

193       Visit    http://lists.ximian.com/mailman/listinfo/mono-docs-list    for
194       details.
195

WEB SITE

197       Visit http://www.mono-project.com for details
198
199
200
201                                                                mdoc-update(1)
Impressum