/
mdoc-update.1
214 lines (207 loc) · 7.27 KB
/
mdoc-update.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
.\"
.\" 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<Type>\fR or
\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\-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
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