215 lines
7.3 KiB
Groff
215 lines
7.3 KiB
Groff
.\"
|
|
.\" 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
|