C#是不是都只能看源码，不提供文档

[liuser666]

先声明我是 C#的新手，保命。

想用 yaml 来做桌面的导入数据和配置文件，有个库叫 yamldotnet,它的官网就给了几个例子。

我的需求是解析 yaml 文件嘛,相关的官网只给了一个 Loading a YAML Stream 的例子.

看了半天才把几个 Class 的定义吃透,这是普遍现象吗?

难道我用一个包都得扒源码才能弄明白这个类是干嘛的吗?....后端都这样吗?太可怕了...

[liuser666]

顺便贴一下代码，很垃圾但可以运行

//本示例演示了 loadstream 功能
using System;
using System.Text;
using System.IO;
using System.Collections.Generic;
using YamlDotNet.RepresentationModel;

namespace YamlDotNet.Samples
{
public class LoadYamlStream
{
public static void Main()
{
// Setup the input
var input = new StringReader(Document);

// Load the stream
var yaml = new YamlStream();
yaml.Load(input);

// Examine the stream
var mapping =
(YamlMappingNode)yaml.Documents[0].RootNode;

PrintValues(mapping);

//foreach (var entry in mapping.Children)
//{
// Console.WriteLine((YamlScalarNode)entry.Key);

//}

//// List all the items
//var items = (YamlSequenceNode)mapping.Children[new YamlScalarNode("items")];
//foreach (YamlMappingNode item in items)
//{
// Console.WriteLine(
// "{0}\t{1}",
// item.Children[new YamlScalarNode("part_no")],
// item.Children[new YamlScalarNode("descrip")]
// );
//}
}
private static void PrintValues(YamlMappingNode mapping,string level="")
{
foreach(var entry in mapping.Children)
{
#nullable enable
string? key = ((YamlScalarNode)entry.Key).Value;
if(key == null)
{
throw new Exception("错误");
}
//先输出键
Console.Write(level+((YamlScalarNode)entry.Key).Value+":");
//判断是否是字符串,即是否到达了底部
var child = mapping.Children[new YamlScalarNode(key)];

if (child.NodeType==YamlNodeType.Scalar)
{
Console.WriteLine(((YamlScalarNode)child).Value);
}//判断节点值是否是 mapping,即是否嵌套
else if (child.NodeType == YamlNodeType.Mapping)
{
Console.WriteLine();
PrintValues((YamlMappingNode)child,level+" ");
}//判断节点值是否是 Sequence,是不是集合
else if (child.NodeType == YamlNodeType.Sequence)
{
Console.WriteLine();
foreach (var value in ((YamlSequenceNode)child))
{
PrintValues((YamlMappingNode)value,level + " ");
}
}

}
level += " ";
}

private const string Document = @"#这是导入文件,通过此文件导入设置以及数据

设置:
开机启动: true
黑夜模式: true
离线模式: false
显示图标: false
#

数据:
- 标题: Visual Code
数据表:
创建数据表: Create database name;
创建表: show create table <表名>;
- 标题: Word
常用操作:
加粗: Ctrl+B
";
}
}

[codehz]

程序员最讨厌的两件事：1. 写文档； 2. 别人不写文档。

[zjsxwc]

应该是太简单了，一个例子就能说明用法，所以不写文档了，🐶

[zjsxwc]

@zjsxwc
而且文档挺全的啊，
https://github.com/aaubry/YamlDotNet/wiki

我看到的 github readme 例子是序列化与反序列化例子，很简单，也不是楼主说的 yamlstream

[k9982874]

作者：我觉得这个简单的库方法名 /类名就能自描述了，不会有傻子看不懂吧
楼主：mmp

[liuser666]

@zjsxwc
我的意思是我的需求是解析一个结构未知的 yaml 文件，然后官网上给的，相关的内容只有一个例子，是 loadyamlstream ，但是涉及的类名都没解释。

[xuanbg]

MSDN

[rioshikelong121]

作为一个半吊子.NET 程序员，我感觉是这样的。.NET 社区里面很多库所谓的文档其实就是接口文档。没有 use case 。。

[cpstar]

额。既然楼上说了没有 use case 的事情，那我就引申一下，有 use case 又有何用。那几个 sample 永远解决不了自己的问题，于是我就得吭哧吭哧看源码，甚至还要反编译出来看源码，只有看了源码才能了解作者的想法，然后落地自己的需要。当然起初看到吐血，但是到了后来反而以此为乐。

[lower]

只能说是某个技术、语言或者库，用的人越多越广泛，主动写教程、demo 的人就越多，各种场景问题 bug 和解决方案就越全……
当年巨硬技术如日中天的时候，网上各种挂着 mvp （微软最有价值专家）头衔的人，大批都在写博客写教程

[Itoktsnhc]

开源项目本身就看运气, 完善还是缺失都很正常。能给出能 work 的 sample 我就觉得很满足了，还有就是大家如果在使用的过程中发现了可能文档没提到的部分，是不是可以考虑比如提个 issu 、pr 来帮助完善呢.

[leeg810312]

所有语言不都这样吗？我用几个语言工作，微软官方的文档已经比较详细了，开源社区的类库就要看作者了，其他开发平台的文档参差不齐。sample 正好符合你的需求，这种情况不多，大多还是要自己尝试

[janus77]

这就叫生态。。。。现在理解一点了吗

[INCerry]

没明白楼主为啥这么写，这个 YAML DotNet 我用过，文档很齐全，读取 yaml 配置简单几行代码就可以了
wiki： https://github.com/aaubry/YamlDotNet/wiki

[x940727]

@leeg810312 Java 的轮子文档质量应该算是所有语言里面最好的了吧？

[liuser666]

@INCerry serialization 和 deserialization 都需要预先定义 yaml 的结构，我需要读取未知结构的 yaml 。

[INCerry]

@liuser666 那你这属于对于这个库来说高阶一些的需求了，确实必须得看源码了

[markgor]

不知道为什么，很多时候我觉得看源码比文档容易理解....

[MaxTan]

@INCerry #17 读取未知结构的 yaml 在 wiki 里面也有提到。 https://github.com/aaubry/YamlDotNet/wiki/Serialization.Deserializer
用 ```deserializer.Deserialize<object>(yamlInput)``` 拿,返回的是一个```IEnumerable<Dictionary<object, object>>```

[liuser666]

@MaxTan 找到啦哈哈哈,感谢感谢,不用自己编了,方便!

[leeg810312]

@x940727 .net 和 JAVA 我都看过文档，官方英语文档质量差不多，但微软有自研的 AI 翻译，可以官方直接提供较高质量机翻的技术文档，主要类库 API 看中文也没有问题，适合不懂英语的开发人员

[rioshikelong121]

@cpstar 实际上来说编写良好的 sample 能覆盖大部分的简单场景，这就是 sample 的价值之所在。如果 API 设计的和你说的非得看源代码才能用，那说明抽象已经泄漏了，也说明这个轮子造的有问题。

[wxw752]

@leeg810312 #21 前几天被迫写客户端，我算是体会到了这个＂较高质量＂的机翻，都是泪。。。

[kelo6]

生态不行啊

[0o0o0o0]

@wxw752 比直接谷歌翻译好很多

[leeg810312]

@wxw752 我看英语文档无障碍，但还是得考虑有人需要中文文档，虽然机器翻译有点生硬，但结合样例代码可以满足大多数需要