Cocona项目：如何为命令行程序添加全局描述信息

在使用Cocona框架开发.NET命令行应用程序时，为程序添加全局描述信息是一个常见的需求。全局描述信息通常用于说明程序的整体功能、用途或重要注意事项，它会在帮助信息的顶部显示，为用户提供对程序的整体认识。

理解Cocona的运行机制

Cocona框架通过Run方法来执行命令行程序。默认情况下，如果直接在Main方法中使用Run，生成的帮助信息会比较基础。要实现更丰富的帮助信息展示，特别是添加全局描述，我们需要使用Run<T>模式。

实现全局描述的两种方式

1. 使用Program类封装

最佳实践是将命令行逻辑封装在一个单独的Program类中，然后通过Run<Program>来执行：

class Program
{
    public static void Main(string[] args)
    {
        CoconaApp.Run<Program>(args);
    }

    // 添加全局描述
    [Cocona.Annotations.Command(Description = "这是一个处理widgets的超级程序")]
    public void Run([Argument] string fooArgument)
    {
        // 程序逻辑
    }
}

2. 直接在Run方法中添加描述

对于简单程序，也可以直接在Run方法上添加描述：

class Program
{
    public static void Main(string[] args)
    {
        CoconaApp.Run(([Argument] string fooArgument) => 
        {
            // 程序逻辑
        },
        settings => {
            settings.Description = "这是一个处理widgets的超级程序";
        });
    }
}

高级定制技巧

除了基本的描述外，Cocona还支持更丰富的帮助信息定制：

1. 多行描述：可以在描述中使用换行符创建多段落
2. 格式化文本：支持基本的Markdown格式
3. 示例代码：可以在描述中添加使用示例

[Cocona.Annotations.Command(
    Description = @"这是一个处理widgets的超级程序

功能特性：
- 高效处理各种widgets
- 支持多种输入格式
- 自动优化处理流程

示例：
  FooProgram sample.wgt")]
public void Run([Argument] string inputFile)
{
    // 程序逻辑
}

注意事项

1. 当使用Run<T>模式时，确保目标类中只有一个标记为[Command]的方法
2. 描述信息应当简洁明了，避免过长
3. 对于复杂的帮助系统，考虑使用IHelpProvider接口进行完全自定义

通过合理使用这些特性，开发者可以创建出既专业又用户友好的命令行帮助信息，显著提升用户体验。