[PAGE ISSUE]: '高效 Dart 语言指南：文档'

[YogiLiu]

页面 URL

https://dart.cn/guides/language/effective-dart/documentation

页面源地址

https://github.com/cfug/dart.cn/tree/master/src/_guides/language/effective-dart/documentation.md

描述问题

dart.cn/src/_guides/language/effective-dart/documentation.md

Lines 523 to 556 in 9ace883

	### DO use prose to explain parameters, return values, and exceptions.
	### **要** 使用散文的方式来描述参数、返回值以及异常信息。
	Other languages use verbose tags and sections to describe what the parameters
	and returns of a method are.
	其他语言使用各种标签和额外的注释来描述参数和返回值。
	{:.bad}
	<?code-excerpt "docs_bad.dart (no-annotations)"?>
	{% prettify dart tag=pre+code %}
	/// Defines a flag with the given name and abbreviation.
	///
	/// @param name The name of the flag.
	/// @param abbr The abbreviation for the flag.
	/// @returns The new flag.
	/// @throws ArgumentError If there is already an option with
	/// the given name or abbreviation.
	Flag addFlag(String name, String abbr) => ...
	{% endprettify %}
	The convention in Dart is to integrate that into the description of the method
	and highlight parameters using square brackets.
	{:.good}
	<?code-excerpt "docs_good.dart (no-annotations)"?>
	{% prettify dart tag=pre+code %}
	/// Defines a flag.
	///
	/// Throws an [ArgumentError] if there is already an option named [name] or
	/// there is already an option using abbreviation [abbr]. Returns the new flag.
	Flag addFlag(String name, String abbr) => ...
	{% endprettify %}

【散文】比较晦涩，翻译不全。

期望如何修复

No response

附加信息

No response