Scaladoc [use case]

Question

Tại sao một số mô tả phương pháp trong Scaladoc bắt đầu bằng [use case]?

Ví dụ: scala.collection.immutable.StringOps.++

Chỉ là trình giữ chỗ được thay thế trong tương lai?

Answer 1

Chúng là những ví dụ đơn giản về cách thức các phương thức này được gọi. Thông thường, các phương pháp này (++, map, flatMap, v.v.) chứa tham số ngầm, thường là đối số được gọi là nhà máy xây dựng (chỉ cần đặt) tóm tắt tạo bộ sưu tập kết quả.

Trong hầu hết các trường hợp, khách hàng của bộ sưu tập không chỉ định các tham số ngầm định này, do đó ScalaDoc cho phép xác định mô tả đơn giản của phương thức - trường hợp sử dụng. Điều này cho phép người dùng nhanh chóng nhận ý tưởng đằng sau phương thức được đề cập và không bị làm phiền với những gì, ví dụ: CanBuildFrom có nghĩa là cách sử dụng.

Ví dụ, đây là việc kê khai đầy đủ các ++:

def ++[B >: A, That](that: TraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That 

Trong hầu hết các trường hợp, các loại bộ sưu tập mục tiêu cũng giống như người nhận cuộc gọi, vì vậy vẻ cuộc gọi khá nhiều, nếu như việc khai báo được như sau (giả sử ++ được định nghĩa trên, nói rằng, List):

def ++(that: TraversableOnce[A]): List[A] 

ở trên, tiềm ẩn đã được giải quyết tại thời gian biên dịch, và các thông số loại là gợi ý đó. Trong hầu hết các trường hợp, điều này nên là quan điểm của khách hàng về phương pháp.

Và nếu bạn muốn chú thích phương pháp của riêng bạn với trường hợp sử dụng, sử dụng thẻ @usecase trong ý kiến ​​doc của bạn:

/** ... 
* ... 
* @usecase def ++(that: TraversableOnce[A]): List[A] 
*/