better scaladoc

Author: rssh

build.sbt

@@ -1,5 +1,5 @@
 //val dottyVersion = "3.0.0-RC2-bin-SNAPSHOT"
-val dottyVersion = "3.0.2"
+val dottyVersion = "3.1.0-RC2"
 //val dottyVersion = dottyLatestNightlyBuild.get
 
 ThisBuild/version := "2.1.1-SNAPSHOT"
@@ -42,12 +42,18 @@ lazy val gopher = crossProject(JSPlatform, JVMPlatform)
          s"-javaagent:${System.getProperty("user.home")}/.ivy2/local/com.github.rssh/trackedfuture_3/0.5.0/jars/trackedfuture_3-assembly.jar"
         )
         */
+        Compile / doc / scalacOptions := Seq("-groups",
+                "-source-links:shared=github://rssh/scala-gopher/master#shared",
+                "-source-links:jvm=github://rssh/scala-gopher/master#jvm"),
         mimaPreviousArtifacts := Set( "com.github.rssh" %% "scala-gopher" % "2.1.0")
     ).jsSettings(
         libraryDependencies += ("org.scala-js" %%% "scalajs-java-logging" % "1.0.0").cross(CrossVersion.for3Use2_13),
         // TODO: switch to ModuleES ?
         scalaJSLinkerConfig ~= { _.withModuleKind(ModuleKind.CommonJSModule) },
         scalaJSUseMainModuleInitializer := true,
+        Compile / doc / scalacOptions := Seq("-groups",
+            "-source-links:shared=github://rssh/scala-gopher/master#shared",
+            "-source-links:js=github://rssh/scala-gopher/master#js"),
     )
 
 lazy val GopherJVM = config("gopher.jvm")

shared/src/main/scala/gopher/Gopher.scala

@@ -10,31 +10,57 @@ import java.util.concurrent.Executor
 
 
 /**
- * core of GopherAPI.
- * Given instance of Gopher[F] need for using most of Gopher operations.
+ * core of Gopher API. Given instance of Gopher[F] need for using most of Gopher operations.
  * 
- * Gopehr API ia a framework, which implements CSP (Communication Sequence Process).
- * Process here - scala units of execution (i.e. )
+ * Gopher is a framework, which implements CSP (Communication Sequence Process).
+ * Process here - scala units of execution (i.e. functions, blok of code, etc). 
+ * Communication channels represented by [gopher.Channel]
+ * 
+ * @see [gopher.Channel]
+ * @see [gopher#select]
  **/
 trait Gopher[F[_]:CpsSchedulingMonad]:
 
   type Monad[X] = F[X]
 
-  
+  /**
+   * Monad which control asynchronic execution.
+   * The main is scheduling: i.e. ability to submit monadic expression to scheduler
+   * and know that this monadic expression will be evaluated.
+   **/
   def asyncMonad: CpsSchedulingMonad[F] = summon[CpsSchedulingMonad[F]]
 
-  
+  /**
+   * Create Read/Write channel. 
+   * @param bufSize - size of buffer. If it is zero, the channel is unbuffered. (i.e. writer is blocked until reader start processing).
+   * @param autoClose - close after first message was written to channel.
+   * @see [gopher.Channel]
+   **/
   def makeChannel[A](bufSize:Int = 0,
                     autoClose: Boolean = false): Channel[F,A,A]                  
 
+  /**
+   * Create channel where you can write only one element.
+   * @see [gopher.Channel]
+   **/                  
   def makeOnceChannel[A](): Channel[F,A,A] =
                     makeChannel[A](1,true)                   
 
+  /***
+   *Create a select statement, which used for choosing one action from a set of potentially concurrent asynchronics events.
+   *[@see gopher.Select] 
+   **/
   def select: Select[F] =
     new Select[F](this)  
 
+  /**
+   * get an object with time operations.
+   **/  
   def time: Time[F] 
 
+  /**
+   * set logging function, which output internal diagnostics and errors from spawned processes.
+   **/
   def setLogFun(logFun:(LogLevel, String, Throwable|Null) => Unit): ((LogLevel, String, Throwable|Null) => Unit)
 
   def log(level: LogLevel, message: String, ex: Throwable| Null): Unit
@@ -55,18 +81,30 @@ trait Gopher[F[_]:CpsSchedulingMonad]:
              ()
      }
 
+end Gopher
 
-  
+
+/**
+* Create Read/Write channel. 
+* @param bufSize - size of buffer. If it is zero, the channel is unbuffered. (i.e. writer is blocked until reader start processing).
+* @param autoClose - close after first message was written to channel.
+* @see [gopher.Channel]
+**/
 def makeChannel[A](bufSize:Int = 0, 
                   autoClose: Boolean = false)(using g:Gopher[?]):Channel[g.Monad,A,A] =
       g.makeChannel(bufSize, autoClose)
+      
 
 def makeOnceChannel[A]()(using g:Gopher[?]): Channel[g.Monad,A,A] =
       g.makeOnceChannel[A]()                   
 
+
 def select(using g:Gopher[?]):Select[g.Monad] =
       g.select
 
+/**
+ * represent `F[_]` as read channel.
+ **/      
 def futureInput[F[_],A](f: F[A])(using g: Gopher[F]): ReadChannel[F,A] =
       val ch = g.makeOnceChannel[Try[A]]()
       g.spawnAndLogFail{

shared/src/main/scala/gopher/Select.scala

@@ -31,14 +31,17 @@ class Select[F[_]](api: Gopher[F]):
       SelectMacro.onceImpl[F,A]('pf, 'api )  
      }    
 
-  /***
+  /**
    * create select groop
    *@see [gopher.SelectGroup]
    **/   
   def group[S]: SelectGroup[F,S] = new SelectGroup[F,S](api)   
 
   def once[S]: SelectGroup[F,S] = new SelectGroup[F,S](api)   
 
+  /**
+   * create Select Loop.
+   **/
   def loop: SelectLoop[F] = new SelectLoop[F](api)
 
 

shared/src/main/scala/gopher/Time.scala

@@ -27,6 +27,9 @@ abstract class Time[F[_]](gopherAPI: Gopher[F]) {
      **/
     type after = FiniteDuration
 
+    /**
+     * return channel, then after `duration` ellapses, send signal to this channel. 
+     **/
     def after(duration: FiniteDuration): ReadChannel[F,FiniteDuration] =
     {
         val ch = gopherAPI.makeOnceChannel[FiniteDuration]()
@@ -39,6 +42,9 @@ abstract class Time[F[_]](gopherAPI: Gopher[F]) {
         ch    
     }
 
+    /**
+     * return future which will be filled after time will ellapse.
+     **/
     def asleep(duration: FiniteDuration): F[FiniteDuration] =
     {
         var fun: Try[FiniteDuration] => Unit = _ => ()
@@ -51,6 +57,9 @@ abstract class Time[F[_]](gopherAPI: Gopher[F]) {
         retval
     }
 
+    /**
+     * synonim for `await(asleep(duration))`.  Should be used inside async block.
+     **/
     transparent inline def sleep(duration: FiniteDuration): FiniteDuration = 
         given CpsSchedulingMonad[F] = gopherAPI.asyncMonad
         await(asleep(duration))
@@ -66,7 +75,9 @@ abstract class Time[F[_]](gopherAPI: Gopher[F]) {
      newTicker(duration).channel
     }
 
-    
+    /**
+    * ticker which hold channel with expirable tick messages and iterface to stop one.
+    **/
     class Ticker(duration: FiniteDuration) {
 
         val channel = gopherAPI.makeChannel[FiniteDuration](0).withExpiration(duration, false)
@@ -97,6 +108,10 @@ abstract class Time[F[_]](gopherAPI: Gopher[F]) {
 
     }
 
+    /**
+     * create ticker with given `duration` between ticks.
+     *@see [gopher.Time.Ticker]
+     **/
     def newTicker(duration: FiniteDuration): Ticker =
     {
         new Ticker(duration)
@@ -108,7 +123,7 @@ abstract class Time[F[_]](gopherAPI: Gopher[F]) {
 
 
     /**
-    * Low lwvel interface for scheduler
+    * Low level interface for scheduler
     */
     def schedule(fun: () => Unit, delay: FiniteDuration): Time.Scheduled
 
@@ -131,6 +146,9 @@ object Time:
     type after = FiniteDuration
 
 
+    /**
+     * return channl on which event will be delivered after `duration`
+     **/
     def after[F[_]](duration: FiniteDuration)(using Gopher[F]): ReadChannel[F,FiniteDuration] =
         summon[Gopher[F]].time.after(duration)