diff --git a/_overviews/scaladoc/for-library-authors.md b/_overviews/scaladoc/for-library-authors.md index 621861450e..dd45d81256 100644 --- a/_overviews/scaladoc/for-library-authors.md +++ b/_overviews/scaladoc/for-library-authors.md @@ -230,6 +230,40 @@ The markup for list blocks looks like: * 1. Third item */ +## Linking to Other Symbols + +Scaladoc supports linking to other classes, methods, and members using +either the `@link` tag or wiki-style links. + +### Using `@link` + +The `@link` tag can be used inside Scaladoc comments to reference other +symbols inline. + +Example: + + /** Returns the length of the given string. + * + * @return the number of characters in this {@link java.lang.String} + */ + def length(s: String): Int = s.length + +You can also link to Scala library types: + + /** Wraps the value in an {@link scala.Option}. */ + def wrap[A](value: A): Option[A] = Option(value) + +### Using Wiki-Style Links + +Alternatively, Scaladoc supports wiki-style links using double brackets: + + /** Returns an [[scala.Option]] containing the result. */ + def find(): Option[Int] = ... + +You can also link to fully-qualified names: + + /** See also [[java.time.LocalDate]] for date handling. */ + ## General Notes for Writing Scaladoc Comments ## - Concise is nice! Get to the point quickly, people have limited time to spend diff --git a/_tour/higher-kinded-types.md b/_tour/higher-kinded-types.md new file mode 100644 index 0000000000..e312ce0f5e --- /dev/null +++ b/_tour/higher-kinded-types.md @@ -0,0 +1,59 @@ +--- +layout: tour +title: Higher-Kinded Types +permalink: /tour/higher-kinded-types.html +--- + +# Higher-Kinded Types + +This section introduces Higher-Kinded Types (HKT), an advanced type system feature in Scala, along with related concepts like type bounds and type projections. + +## What are Higher-Kinded Types? + +Higher-Kinded Types allow abstracting over type constructors. For example: + +```scala +trait Functor[F[_]] { + def map[A, B](fa: F[A])(f: A => B): F[B] +} +``` + +Here `F[_]` is a type constructor that takes a single type parameter. + +### Example Usage: + +```scala +val optionFunctor = new Functor[Option] { + def map[A, B](fa: Option[A])(f: A => B): Option[B] = fa.map(f) +} + +val result = optionFunctor.map(Some(2))(_ * 2) // Some(4) +``` + +## Type Bounds and Typeclasses + +Scala supports upper and lower bounds and commonly uses typeclasses for comparison: + +```scala +def max[T](x: T, y: T)(implicit ord: Ordering[T]): T = + if (ord.gt(x, y)) x else y +``` + +Here `Ordering[T]` provides comparison logic for type `T` using a typeclass pattern. + +## Type Projections + +You can refer to a type member of another type: + +```scala +class Outer { + class Inner +} + +val o = new Outer +val i: o.Inner = new o.Inner +``` + +## Summary + +These features allow Scala developers to write highly abstract and reusable code. Higher-Kinded Types, type bounds, and type projections are cornerstones of Scala’s expressive type system.