Rust语言 - 接口设计的建议之显而易见（Obvious） - ToB企服应用市场:ToB评测及商务社交产业平台

// Panic（恐慌）是这两种情况的一个很好的例子：如果代码可能发生 Panic，请在文档中明确说明这一点，以及可能导致 Panic 的情况。
// 同样，如果代码可能返回错误，请记录它返回错误的情况。
// 对于 unsafe 的函数，请记录调用者必须保证什么条件，才能确保调用时安全的。
/// 除法运算，返回两个数的结果。
///
/// # Panics
///
/// 如果除数为零，该函数会发生 panic。
///
/// # 示例
///
/// ```
/// let result = divide(10, 2);
/// assert_eq!(result, 5);
/// ```
pub fn divide(dividend: i32, divisor: i32) -> i32 {
// 实现代码 ...
}

复制代码

/// 一个简单的模块，包含一些用于内部使用的函数和结构体。
pub mod internal {
/// 一个用于内部计算的辅助函数。
#[doc(hidden)]
pub fn internal_helper() {
// 内部计算的具体实现 ...
}
/// 一个仅用于内部使用的结构体。
#[doc(hidden)]
pug struct InternalStruct {
// 结构体的字段和方法 ...
}
}
/// 一个公共接口函数，调用了内部的辅助函数。
pub fn public_function() {
// 调用内部辅助函数
internal::internal_helper();
}
/// 一个公共结构体，包含一些公共字段和方法。

复制代码

//! 这是一个用于处理图像的库。
//!
//! 这个库提供了一些常用的图像处理功能，例如：
//! - 读取和保存不同格式的图像文件 [`Image::load`] [`Image::save`]
//! - 调整图像的大小、旋转和裁剪 [`Image::resize`] [`Image::rotate`] [`Image::crop`]
//! - 应用不同的滤镜和效果 [`Filter`] [`Effect`]
//!
//! 如果您想了解更多关于图像处理的原理和算法，您可以参考以下的资源：
//! - [数字图像处理](https://book.douban.com/subject/5345798/)，一个经典的教科书，介绍了图像处理的基本概念和方法。
//! - [Learn OpenCV](https://learnopencv.com/)，一个网站，提供了很多用OpenCV实现图像处理功能的教程和示例代码。
//! - [Awesome Computer Vision](https://github.com/jbhuang0604/awesome-computer-vision)，一个GitHub仓库，收集计算机视觉资源。
/// 一个表示图像的结构体
#[derive(Debug, Clone)]
pub struct Image {
// ...
}
impl Image {
/// 从指定的路径加载一个图像文件
///
/// 支持的格式有：PNG、JPEG、GIF、BMP 等
///
/// # 参数
///
/// - `path`: 图像文件的路径
///
/// # 返回值
///
/// 如果成功，返回一个 [`Image`] 实例；如果失败，返回一个 [`Error`]。
///
/// # 示例
///
/// ```no_run
/// use image::Image;
///
/// let img = Image::load("test.png")?;
/// ```
#[doc(alias = "读取")]
#[doc(alias = "打开")]
pub fn load<P: AsRef<Path>>(path: P) -> Result<Self, Error> {
// ...
}
/// 将图像保存到指定的路径
///
/// 支持的格式有：PNG、JPEG、GIF、BMP 等
///
/// # 参数
///
}

复制代码

/// 一个只在启用了 `foo` 特性时才可用的结构体。
#[cfg(feature = "foo")]
#[doc(cfg(feature = "foo"))]
pub struct Foo;
impl Foo {
/// 一个只在启用了 `foo` 特性时才可用的方法。
#[cfg(feature = "foo")]
#[doc(cfg(feature = "foo"))]
pub fn bar(&self) {
// ...
}
}
fn main() {
println!("Hello, world!");
}

复制代码

fn processDate(dryRun: bool, overwrite: bool, validate: bool) {
// 处理数据的逻辑
}
enum DryRun {
Yes,
No,
}
enum Overwrite {
Yes,
No,
}
enum Validate {
Yes,
No,
}
fn processData(dryRun: DryRun, overwrite: Overwrite, validate: Validate) {
// 处理数据的逻辑
}
processData(DryRun::Yes, Overwrite::No, Validate::Yes);
fn main() {
println!("Hello, world!");
}

复制代码

struct Grounded;
struct Launched;
// and so on
enum Color {
White,
Black,
}
struct Kilograms(u32);
struct Rocket<Stage = Grounded> {
stage: std::marker::PhantomData<Stage>,
}
impl Default for Rocket<Grounded> {
fn default() -> Self {
Self {
stage: Default::default()
}
}
}
impl Rocket<Grounded> {
pub fn launch(self) -> Rocket<Launched> {
Rocket {
stage: Default::default(),
}
}
}
impl Rocket<Launched> {
pub fn accelerate(&mut self) {}
pub fn decelerate(&mut self) {}
}
impl<Stage> Rocket<Stage> {
pub fn color(&self) -> Color {
Color::White
}
pub fn weight(&self) -> Kilograms {
Kilograms(0)
}
}
fn main() {
println!("Hello, world!");
}

复制代码

#[must_use]
fn process_data(data: Data) -> Result<(), Error> {
// 处理数据的逻辑
Ok(())
}
// 在这个示例中，我们使用 #[must_use] 注解将 process_data 函数标记为必须使用期返回值。
// 如果用户在调用该函数后没有显式处理返回的 Result 类型，编译器将发出警告。
// 这有助于提醒用户在处理潜在的错误情况时要小心，并减少可能得错误。
fn main() {
println!("Hello, world!");
}

复制代码