xenial (1) mdoc-update.1.gz

Provided by: monodoc-base_4.2.1.102+dfsg2-7ubuntu4_all bug

NAME

       mdoc update - mdoc(5) documentation format support

SYNOPSIS

       mdoc update [OPTIONS]* ASSEMBLIES

DESCRIPTION

       mdoc update is responsible for the following:

       *      Creating  documentation  stubs  based  on  ASSEMBLIES.   The stub-creation process will create new
              mdoc(5) XML files for each type within ASSEMBLIES, and provide documentation stubs for each member
              of those types.

       *      Update  documentation stubs based on ASSEMBLIES.  Existing mdoc(5) documentation can be updated to
              reflect changes within ASSEMBLIES, such as added types  and  members,  while  preserving  existing
              documentation.

              In  some  limited circumstances, renames will be tracked, minimizing the documentation burden when
              e.g. a parameter is renamed.

       mdoc update does not  rely  on  documentation  found  within  source  code,  though  it  can  import  XML
       Documentation Comments via the -i option.

       See mdoc(1) and mdoc(5) for more information.

OPTIONS

       --delete
              Allow  mdoc  update  to  delete  members  from  documentation files.  The only members deleted are
              members which are no longer present within ASSEMBLIES and are not present in  any  other  assembly
              versions.

              If  a  type is no longer present, the documentation file is not deleted, but is instead renamed to
              have a .remove  extension.

              Version detection is done with the //AssemblyVersion elements; if there are  no  //AssemblyVersion
              elements  for  a  given  <Type> or <Member/>, then the <Type> will be renamed and/or the <Member/>
              will be removed.

       --exceptions[=SOURCES]
              EXPERIMENTAL.  This is not 100% reliable, but is intended to serve as  an  aid  for  documentation
              writers.

              Inspect member bodies to determine what exceptions can be generated from the member.

              SOURCES  is  an optional comma-separated list of the following sources that should be searched for
              exceptions:

                      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.

              If SOURCES isn't provided (the default), then only exceptions created  within  the  member  itself
              will be documented.

              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:

              *      This will not find exceptions which are implicit to the IL, such as  NullReferenceException
                     and IndexOutOfRangeException.

              *      This will find exceptions which are not thrown, e.g.

                         public void CreateAnException ()
                         {
                             Exception e = new Exception ();
                         }

              *      This will not "follow" delegate and interface calls:

                         public void UsesDelegates ()
                         {
                             Func<int, int> a = x => {throw new Exception ();};
                             a (4);
                         }

                     The function UsesDelegates() won't have any exceptions documented.

              *      This  will  find  exceptions  which  "cannot  happen",  such  as ArgumentNullExceptions for
                     arguments which are "known" to be non-null:

                         public void A ()
                         {
                             B ("this parameter isn't null");
                         }

                         public void B (string s)
                         {
                             if (s == null)
                                 throw new ArgumentNullException ("s");
                         }

                     For the above, if --exceptions=asm is provided then A() will be documented as  throwing  an
                     ArgumentNullException, which cannot happen.

       -f=FLAG
              Specify a flag to alter behavior.  Valid flags include:

              no-assembly-versions
                     See the -fno-assembly-versions documentation, below.

       -fno-assembly-versions
              Do not generate /Type/AssemblyInfo/AssemblyVersion and /Type/Members/Member/AssemblyInfo elements.

              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
              //AssemblyVersion  element,  thus  increasing  the  amount  of  changes  that  need  review before
              committing (assuming all changes are actually reviewed before commit).

              WARNING: This will interact badly with the --delete option, as --delete uses the //AssemblyVersion
              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
              System.Text.UTF8Encoding.GetBytes(string) (which is present in .NET 1.0 but not in .NET 2.0), then
              the member will be removed when the --delete -fno-assembly-versions  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.

              Consequently, this option should only be specified if types and members will never be removed from
              an assembly.

       -i, --import=FILE
              Import documentation found within FILE.

              FILE may contain either csc /doc XML or ECMA-335 XML.

       -L, --lib=DIRECTORY
              Add DIRECTORY to the assembly search path, so that dependencies of ASSEMBLIES can be found without
              documenting those assemblies.

       -o, --out=DIRECTORY
              Place the generated stubs into DIRECTORY.

              When updating documentation, DIRECTORY is also the source directory.

       -r=ASSEMBLY
              ASSEMBLY is a dependency for one of ASSEMBLIES which should not be documented but is  required  to
              process one of ASSEMBLIES.  Add the directory containing ASSEMBLY to the assembly search path.

              This option is equivalent to specifying -L `dirname ASSEMBLY`.

       --since=VERSION
              When updating documentation for an assembly, if a type or member is encountered which didn't exist
              in the previous version of the assembly a <since version="VERSION"/> element will be inserted.

       --type=TYPE
              Only update documentation for the type TYPE.

       -h, -?, --help
              Display a help message and exit.

SEE ALSO

       mdoc(1), mdoc(5), mdoc-assemble(1), mdoc-export-html(1), mdoc-validate(1),

MAILING LISTS

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

WEB SITE

       Visit http://www.mono-project.com for details

                                                                                                  mdoc-update(1)