c#如何使用 XML 文档功能
作者:olprod 发布时间:2023-12-25 03:44:33
下面的示例提供对某个已存档类型的基本概述。
示例
// If compiling from the command line, compile with: -doc:YourFileName.xml
/// <summary>
/// Class level summary documentation goes here.
/// </summary>
/// <remarks>
/// Longer comments can be associated with a type or member through
/// the remarks tag.
/// </remarks>
public class TestClass : TestInterface
{
/// <summary>
/// Store for the Name property.
/// </summary>
private string _name = null;
/// <summary>
/// The class constructor.
/// </summary>
public TestClass()
{
// TODO: Add Constructor Logic here.
}
/// <summary>
/// Name property.
/// </summary>
/// <value>
/// A value tag is used to describe the property value.
/// </value>
public string Name
{
get
{
if (_name == null)
{
throw new System.Exception("Name is null");
}
return _name;
}
}
/// <summary>
/// Description for SomeMethod.
/// </summary>
/// <param name="s"> Parameter description for s goes here.</param>
/// <seealso cref="System.String">
/// You can use the cref attribute on any tag to reference a type or member
/// and the compiler will check that the reference exists.
/// </seealso>
public void SomeMethod(string s)
{
}
/// <summary>
/// Some other method.
/// </summary>
/// <returns>
/// Return values are described through the returns tag.
/// </returns>
/// <seealso cref="SomeMethod(string)">
/// Notice the use of the cref attribute to reference a specific method.
/// </seealso>
public int SomeOtherMethod()
{
return 0;
}
public int InterfaceMethod(int n)
{
return n * n;
}
/// <summary>
/// The entry point for the application.
/// </summary>
/// <param name="args"> A list of command line arguments.</param>
static int Main(System.String[] args)
{
// TODO: Add code to start application here.
return 0;
}
}
/// <summary>
/// Documentation that describes the interface goes here.
/// </summary>
/// <remarks>
/// Details about the interface go here.
/// </remarks>
interface TestInterface
{
/// <summary>
/// Documentation that describes the method goes here.
/// </summary>
/// <param name="n">
/// Parameter n requires an integer argument.
/// </param>
/// <returns>
/// The method returns an integer.
/// </returns>
int InterfaceMethod(int n);
}
该示例生成一个包含以下内容的 .xml 文件。
<?xml version="1.0"?>
<doc>
<assembly>
<name>xmlsample</name>
</assembly>
<members>
<member name="T:TestClass">
<summary>
Class level summary documentation goes here.
</summary>
<remarks>
Longer comments can be associated with a type or member through
the remarks tag.
</remarks>
</member>
<member name="F:TestClass._name">
<summary>
Store for the Name property.
</summary>
</member>
<member name="M:TestClass.#ctor">
<summary>
The class constructor.
</summary>
</member>
<member name="P:TestClass.Name">
<summary>
Name property.
</summary>
<value>
A value tag is used to describe the property value.
</value>
</member>
<member name="M:TestClass.SomeMethod(System.String)">
<summary>
Description for SomeMethod.
</summary>
<param name="s"> Parameter description for s goes here.</param>
<seealso cref="T:System.String">
You can use the cref attribute on any tag to reference a type or member
and the compiler will check that the reference exists.
</seealso>
</member>
<member name="M:TestClass.SomeOtherMethod">
<summary>
Some other method.
</summary>
<returns>
Return values are described through the returns tag.
</returns>
<seealso cref="M:TestClass.SomeMethod(System.String)">
Notice the use of the cref attribute to reference a specific method.
</seealso>
</member>
<member name="M:TestClass.Main(System.String[])">
<summary>
The entry point for the application.
</summary>
<param name="args"> A list of command line arguments.</param>
</member>
<member name="T:TestInterface">
<summary>
Documentation that describes the interface goes here.
</summary>
<remarks>
Details about the interface go here.
</remarks>
</member>
<member name="M:TestInterface.InterfaceMethod(System.Int32)">
<summary>
Documentation that describes the method goes here.
</summary>
<param name="n">
Parameter n requires an integer argument.
</param>
<returns>
The method returns an integer.
</returns>
</member>
</members>
</doc>
编译代码
若要编译该示例,请输入以下命令:
csc XMLsample.cs /doc:XMLsample.xml
此命令创建 XML 文件 XMLsample.xml,可在浏览器中或使用 TYPE 命令查看该文件。
可靠编程
XML 文档以 /// 开头。 创建新项目时,向导会放置一些以 /// 开头的行。 处理这些注释时存在一些限制:
1.文档必须是格式正确的 XML。 如果 XML 格式不正确,则会生成警告,并且文档文件将包含一条注释,指出遇到错误。
2.开发人员可以随意创建自己的标记集。 有一组推荐的标记。 部分建议标记具有特殊含义:
<param> 标记用于描述参数。 如果已使用,编译器会验证该参数是否存在,以及文档是否描述了所有参数。 如果验证失败,编译器会发出警告。
cref 属性可以附加到任何标记,以引用代码元素。 编译器验证此代码元素是否存在。 如果验证失败,编译器会发出警告。 编译器在查找 cref 属性中描述的类型时会考虑所有 using 语句。
<summary> 标记由 Visual Studio 中的 IntelliSense 用于显示有关某个类型或成员的附加信息。
备注
XML 文件不提供有关该类型和成员的完整信息(例如,它不包含任何类型信息)。 若要获取有关类型或成员的完整信息,请将文档文件与对实际类型或成员的反射一起使用。
来源:https://docs.microsoft.com/zh-cn/dotnet/csharp/programming-guide/xmldoc/how-to-use-the-xml-documentation-features
猜你喜欢
- 单链表:每个数据是以节点的形式存在的每个节点分为数据域和指针域数据域中保存该节点的数据指针域中保存指向下一个节点的指针实现思路:节点类Sin
- 本文介绍了Android 实现截屏方式整理,分享给大家。希望对大家有帮助可能的需求:截自己的屏截所有的屏带导航栏截屏不带导航栏截屏截屏并编
- 如果需要集合中的元素何时删除或添加的信息,可以使用ObservableCollection<T>类。这个类是为WPF定义的,这样
- 前言在学习android中图形图像处理技术这部分内容时,对绘制圆弧函数canvas.drawArc()的用法、参数含义及画图原理很是不理解,
- JDK SPI是什么最近工作中听几个同事说了好几次SPI这个名词,虽然和我没关系,但是心里默默想还是学习一下,不然下次和我说到SPI,连是什
- Talk is cheap, show me the code!先来看代码:public class TestEval {public st
- 前 言🍉 作者简介:半旧518,长跑型选手,立志坚持写10年博客,专注于java后端☕专栏简介:深入、全面、系统的介绍消息中间件🌰 文章简介
- 本文实例讲述了C#使用XML序列化操作菜单的方法。分享给大家供大家参考。具体分析如下:之前的一篇文章《C#递归读取XML菜单数据的方法》没使
- 使用AES算法可用于对数据进行加密码与解密,使用的时候需要注意两点:1)被加密的串越长,加密后的字符串越长,注意数据库字段的设计;2)Lin
- 我们知道,编写一个Java程序后,如果想让自己编写的代码可以正常运行,我们便需要对它进行编译和运行,而Java环境变量的配置就显得尤为重要,
- 摘要:Java8通过Function获取字段名,解决硬编码,效果类似于mybatis-plus的LambdaQueryWrapper。本文总
- 一、问题重现1.配置文件spring: #DataSource数据源 datasource: &nbs
- iText介绍和说明因为项目需要生成PDF文件,所以去找了一下能够生成PDF的Java工具,看到了iText可以说好评如潮。如果你想通过ja
- 1.更新同步方式:/** * 三个参数 * the path of the node
- 一次正常的请求最近别人需要调用我们系统的某一个功能,对方希望提供一个api让其能够更新数据。由于该同学是客户端开发,于是有了类似以下代码。@
- 项目描述:这是一个基于SpringBoot+Vue框架开发的仿小米电子产品售卖商城系统。首先,这是一个前后端分离的项目,代码简洁规范,注释说
- 一般来讲,项目更换JDK版本的情况比较少,但是有时难免会遇到。电脑安装不同版本的JDK这里不做介绍。这里记录一下修改项目JDK版本要注意的几
- Android中Progress的简单实例Android中Progress网上的demo都是瞎扯淡,当然,你们也可以认为我的demo是瞎扯淡
- Java Config 下的Spring Test方式用了三种方式:1.纯手动取bean:package com.wang.test;imp
- 1.后台参数校验Spring Validation验证框架对参数的验证机制提供了@Validated(Spring JSR-303规范,是标