标签: xml-documentation

我实际上正在寻找指导方针，如何在 C#-DLL 内的公共方法中记录多个异常。

例子：

/// <summary>
/// This method does something
/// </summary>
/// <param name="p_Parameter1">First parameter</param>
/// <param name="p_Parameter2">Second parameter</param>
/// <param name="p_Number">A number</param>
/// <exception cref="ArgumentNullException">
/// Thrown if p_Parameter1 is null</exception>
/// <exception cref="ArgumentNullException">
/// Thrown if p_Parameter2 is null</exception>
/// <exception cref="ArgumentNullException">
/// Thrown if any element of p_Parameter2 is null</exception>
/// <exception cref="ArgumentOutOfRangeException">
/// Thrown if p_Number is below or equal 0</exception>
/// <returns>A object</returns>

public static object DoSomething(
    object p_Parameter1, IList<object> p_Parameter2, 
    object p_Parameter3, …

我最近使用 Sandcastle 来记录我的类库。但是，我最近发现 Sandcastle 不再由 Microsoft 开发：https : //archive.codeplex.com/? p=sandcastle 。

我在 GitHub 上在线查看过，我发现这些天很多开源项目都使用 .MD (MarkDown) 文件。我看到 .MD 文件受 GitHub 和 TFS 支持。如何从 XML 文档文件生成 .MD 文件？

我花了最后几个小时在谷歌上搜索这个。例如，我只下载了几百次就发现了这个：https : //github.com/lijunle/Vsxmd/tree/master/Vsxmd 我不是在寻求工具推荐。我在问是否可以将 .XML 文档转换为 .MD 文件。

我正在尝试在类的成员上使用XML文档,在某些情况下,我想使用标记引用泛型类型.这里的问题是当指定多个泛型类型参数时会生成警告.很容易找到如何使用单个参数引用泛型类型,如下所示:

<see cref="Func{int}" />

但是,尝试这样的事情会产生警告:

<see cref="Func{int, bool}" />

对于具有多个类型参数的引用,我似乎使用了错误的语法,或者在C#的XML文档中目前不支持此类引用.奇怪的是,我似乎无法在MSDN或Sandcastle文档中找到有关此内容的任何信息(我正在使用它来编译文档,并且还抱怨语法).这里的任何澄清将不胜感激.

我是一个巨大的.NET XML文档的风扇.

但是,我可以诚实地说,我从未见过教程或项目,例如,我们有这样的标记:

/// <summary>
/// dummy text
/// </summary>
/// <returns>blah</returns>
public ActionResult LogOff() {
    FormsService.SignOut();

    return RedirectToAction("Index", "Home");
}

代替:

// **************************************
// URL: /Account/LogOff
// **************************************

public ActionResult LogOff() {
    FormsService.SignOut();

    return RedirectToAction("Index", "Home");
}

这有什么特别的原因吗？我是唯一一个想要记录我的Controller方法的人吗？

编辑1:

虽然大多数控制器方法看起来很简单,但详细说明的问题如何说明这个问题:MVC:如何使用具有许多子实体的实体？？

在我的实现中，我有这个：

/// <inheritdoc cref="IInterface{T} this[,]"/>
public T this[long row, long column]
{
    ...
}

XMLdoc 已经存在于IInterface. 我怎样才能从那里拿起它（就像我做其他事情一样）？

我收到编译器警告：

“XXX.YYY.this[long, long]”上的警告 108 XML 注释具有语法错误的 cref 属性“IInterface this[,]”

我试图消除this从cref但这也不能工作。我需要什么语法？

有时我会覆盖基类中的方法.有时我甚至用空方法覆盖它们,因为我想要的是防止这种行为.

在过去,我会写这样的东西来表明绕过基本方法的意图:

protected override void OnMouseUp(MouseEventArgs e)
{
    // base.OnMouseUp(e);
}

(我知道注释的代码行是一件坏事.我曾经这么做过)

但我想做得更好:

• 如何记录覆盖的意图？特别:
• 我在override的XML(<summary>？)文档中写了什么？

我正在使用DITA生成用户文档,并生成PDF和XHTML可交付成果.我可以使用哪种DITA元素嵌入YouTube视频？

理想情况下,我更喜欢使用样式表生成嵌入代码,并以某种方式在文档中添加视频链接.以下是我设想这样一个元素可能使用伪标记的方式:

<fig audience="web">
    <title>YouTube 101: How to Find What's Hot on YouTube</title>
    <video href="http://www.youtube.com/watch?feature=player_embedded&v=FEyRza0rJyI">
        <alt>This video explains how to tap into the cultural zeitgeist happening on YouTube right now.</alt>
    </video>
</fig>

如果可能的话,我宁愿使用其中一个标准DITA元素来实现这一目标.

在一个相当大的C＃项目上工作，该项目已经可以使用简单的类似变量，所以可以说我有这样的作品

    double
        TempAngle = 1,
        AngleCountDown = HalfSight,
        SightAngleFromCopter = 0;

如何像执行方法一样记录它们（见下文）？

    /// <summary>
    /// general explanation
    /// </summary>
    /// <param name="a">some hole num</param>
    /// <param name="b">some string</param>
    public MainWindow( int a ,string b)
    {} 

最后，我想做的就是写点东西

    /// <param name="TempAngle">some</param>
    /// <param name="AngleCountDown">something</param>
    /// <param name="SightAngleFromCopter">something else</param>
    double
        TempAngle = 1,
        AngleCountDown = HalfSight,
        SightAngleFromCopter = 0;

我正在开发一个小类，使用我的重载方法，如下所示：

/// <summary>
/// some description about myMethod
/// </summary>
/// <param name="arg1"></param>
/// <param name="arg2"></param>
/// <returns></returns>
public string myMethod(string arg1, string arg2) { };
public string myMethod(string arg1){};

问题是采用一个参数的方法没有在标签中显示描述。我应该将相同的摘要标签单独添加到第二种方法中吗？我觉得有点烦人，因为 myMethod 描述应该有相同的标签描述，尽管参数描述可能会有所不同。

有没有办法让重载方法共享一个描述？

我有一个以下摘要片段.

  /// <summary>
  ///  Holds the future state for 4 pixels
  ///  Every pixel can be in 4 states, on, off, unknown, or don't care
  ///  Off=00, on=01, unknown = 10, don't care = 11.
  ///   The grid is like this:
  ///   <code>
  ///      TL|TR        <br/>
  ///     ---+---       <br/>
  ///      BL|BR        <br/>
  ///  </code>
  /// </summary>

这在弹出提示中显示为:

保持4像素的未来状态每个像素可以处于4种状态,
开,关,未知,或者不关心关= 00,开= 01,未知= 10,
不关心= 11.网格是这样的: TL|TR ---+--- BL|BR

中间的ascii艺术以等宽字体正确显示,但没有换行符.
如何正确显示换行符