Update documentation and readme

Author: kornilova203

README.md

@@ -53,15 +53,35 @@ object vector {
       def y: native.CFloat = !p._2
       def y_=(value: native.CFloat): Unit = !p._2 = value
     }
-    def struct_point()(implicit z: native.Zone): native.Ptr[struct_point] = native.alloc[struct_point]
 
     implicit class struct_vector_ops(val p: native.Ptr[struct_vector]) extends AnyVal {
       def a: native.Ptr[struct_point] = p._1
       def a_=(value: native.Ptr[struct_point]): Unit = !p._1 = !value
       def b: native.Ptr[struct_point] = p._2
       def b_=(value: native.Ptr[struct_point]): Unit = !p._2 = !value
     }
-    def struct_vector()(implicit z: native.Zone): native.Ptr[struct_vector] = native.alloc[struct_vector]
+  }
+
+  object struct_point {
+    import implicits._
+    def apply()(implicit z: native.Zone): native.Ptr[struct_point] = native.alloc[struct_point]
+    def apply(x: native.CFloat, y: native.CFloat)(implicit z: native.Zone): native.Ptr[struct_point] = {
+      val ptr = native.alloc[struct_point]
+      ptr.x = x
+      ptr.y = y
+      ptr
+    }
+  }
+
+  object struct_vector {
+    import implicits._
+    def apply()(implicit z: native.Zone): native.Ptr[struct_vector] = native.alloc[struct_vector]
+    def apply(a: native.Ptr[struct_point], b: native.Ptr[struct_point])(implicit z: native.Zone): native.Ptr[struct_vector] = {
+      val ptr = native.alloc[struct_vector]
+      ptr.a = a
+      ptr.b = b
+      ptr
+    }
   }
 }
 ```

build.sbt

@@ -146,6 +146,10 @@ lazy val docs = project("docs")
         .link("vector")
         .packageName("org.example")
     },
+    nativeBindgenPath := {
+      Some(
+        (ThisBuild / baseDirectory).value / "bindgen/target/scala-native-bindgen")
+    },
     Test / nativeBindgen / target := (Test / scalaSource).value / "org/example",
     nativeLinkStubs := true,
     compileTask("vector", Test / resourceDirectory),

docs/src/paradox/using-generated-bindings.md

@@ -4,47 +4,52 @@ Consider following header file:
 
 @@snip [vector.h] (../test/resources/vector.h)
 
-Bindgen will generate type aliases for the structs, binding for function `add`
-and helper functions that make usage of structs easier.
+Bindgen will output
+ * type aliases for the structs
+ * binding for function `cosine`
+ * helper functions that make usage of structs easier
 
 @@snip [vector.h] (../test/scala/org/example/vector.scala)
 
-Let's write code that creates two vectors, adds them and prints resulting
-vector.
+Let's write code that creates two line segments and prints angel between them.
 
-First we need to create points for vectors. We will use `native.Zone` to
+First we need to create points. We will use `native.Zone` to
 allocate struct (more information on memory management can be found
 here: [Scala Native memory management]).
 
-Helper object `mylibHelpers` contains function for struct allocation.
-To import it use `import mylibHelpers._`
+Generated bindings contain helper functions that make struct allocation easier.
+To import them use `import org.example.vector._`
 
-Let's create points for first vector:
+Let's create two points and the first line segment:
 
 @@snip [step-1] (../test/scala/org/scalanative/bindgen/docs/VectorSpec.scala) { #step-1 }
 
-Now we want to set fields of created points. Scala Native provides access
-to fields by using `_N` methods where `N` is index of a field
-(see [Scala Native memory layout types]).
+There is no need to create points manually, just call `struct_lineSegment`
+constructor and set point coordinates using fields setters.
 
-Bindgen generates implicit helper classes that wrap calls to `_N` in functions
-with meaningful names. We already imported helper class, so we can use the
-functions:
+Scala Native allows us to access a field by using `_N` method where `N` is index of a field
+(see [Scala Native memory layout types]) but it is not convenient because we have to
+match indices with fields names.
+
+Bindgen provides implicit helper classes that wrap calls to `_N` in functions
+with meaningful names. To import these classes add `import org.example.vector.implicits._`
+to your code:
 
 @@snip [step-2] (../test/scala/org/scalanative/bindgen/docs/VectorSpec.scala) { #step-2 }
 
-Lets create first vector. Note that `struct_vector` contains
-fields of type `struct_point` but setters accept variables of type
-`native.Ptr[struct_point]`. It helps to avoid Scala Native limitation that
-does not allow passing structs and arrays by value
-(see @github[scala-native/scala-native#555](scala-native/scala-native#555)).
+@@@ note
+
+Note that `struct_lineSegment` contains fields of value type `struct_point`
+but setters accept variables of type `native.Ptr[struct_point]`.
+It helps to avoid Scala Native limitation that does not allow passing structs
+and arrays by value (see @github[scala-native/scala-native#555](scala-native/scala-native#555)).
+
+@@@
 
-@@snip [step-3] (../test/scala/org/scalanative/bindgen/docs/VectorSpec.scala) { #step-3 }
+Now we can calculate angel between line segments:
 
-Repeat these steps to create second vector. Once both vectors are created we can
-call `add` function and print the result:
+@@snip [step-3] (../test/scala/org/scalanative/bindgen/docs/VectorSpec.scala) { #step-2 }
 
-@@snip [step-4] (../test/scala/org/scalanative/bindgen/docs/VectorSpec.scala) { #step-4 }
 
  [Scala Native memory management]: http://www.scala-native.org/en/latest/user/interop.html#memory-management
  [Scala Native memory layout types]: http://www.scala-native.org/en/latest/user/interop.html#memory-layout-types

docs/src/test/resources/vector.c

@@ -1,16 +1,13 @@
 #include "vector.h"
+#include <math.h>
 #include <stdlib.h>
 
-struct vector *add(struct vector *v1, struct vector *v2) {
-    struct vector *out = malloc(sizeof(struct vector));
-
-    if (!out)
-        return NULL;
-
-    out->a.x = v1->a.x + v2->a.x;
-    out->a.y = v1->a.y + v2->a.y;
-    out->b.x = v1->b.x + v2->b.x;
-    out->b.y = v1->b.y + v2->b.y;
-
-    return out;
-}
+float cosine(struct lineSegment *v1, struct lineSegment *v2) {
+    float v1x = fabsf(v1->b.x - v1->a.x);
+    float v1y = fabsf(v1->b.y - v1->a.y);
+    float v1Length = sqrtf(v1x * v1x + v1y * v1y);
+    float v2x = fabsf(v2->b.x - v2->a.x);
+    float v2y = fabsf(v2->b.y - v2->a.y);
+    float v2Length = sqrtf(v2x * v2x + v2y * v2y);
+    return (v1x * v2x + v1y * v2y) / (v1Length * v2Length);
+}

docs/src/test/resources/vector.h

@@ -3,9 +3,9 @@ struct point {
     float y;
 };
 
-struct vector {
+struct lineSegment {
     struct point a;
     struct point b;
 };
 
-struct vector *add(struct vector *v1, struct vector *v2);
+float cosine(struct lineSegment *v1, struct lineSegment *v2);

docs/src/test/scala/org/example/vector.scala

@@ -7,8 +7,8 @@ import scala.scalanative.native._
 @native.extern
 object vector {
   type struct_point = native.CStruct2[native.CFloat, native.CFloat]
-  type struct_vector = native.CStruct2[struct_point, struct_point]
-  def add(v1: native.Ptr[struct_vector], v2: native.Ptr[struct_vector]): native.Ptr[struct_vector] = native.extern
+  type struct_lineSegment = native.CStruct2[struct_point, struct_point]
+  def cosine(v1: native.Ptr[struct_lineSegment], v2: native.Ptr[struct_lineSegment]): native.CFloat = native.extern
 
   object implicits {
     implicit class struct_point_ops(val p: native.Ptr[struct_point]) extends AnyVal {
@@ -17,14 +17,34 @@ object vector {
       def y: native.CFloat = !p._2
       def y_=(value: native.CFloat): Unit = !p._2 = value
     }
-    def struct_point()(implicit z: native.Zone): native.Ptr[struct_point] = native.alloc[struct_point]
 
-    implicit class struct_vector_ops(val p: native.Ptr[struct_vector]) extends AnyVal {
+    implicit class struct_lineSegment_ops(val p: native.Ptr[struct_lineSegment]) extends AnyVal {
       def a: native.Ptr[struct_point] = p._1
       def a_=(value: native.Ptr[struct_point]): Unit = !p._1 = !value
       def b: native.Ptr[struct_point] = p._2
       def b_=(value: native.Ptr[struct_point]): Unit = !p._2 = !value
     }
-    def struct_vector()(implicit z: native.Zone): native.Ptr[struct_vector] = native.alloc[struct_vector]
+  }
+
+  object struct_point {
+    import implicits._
+    def apply()(implicit z: native.Zone): native.Ptr[struct_point] = native.alloc[struct_point]
+    def apply(x: native.CFloat, y: native.CFloat)(implicit z: native.Zone): native.Ptr[struct_point] = {
+      val ptr = native.alloc[struct_point]
+      ptr.x = x
+      ptr.y = y
+      ptr
+    }
+  }
+
+  object struct_lineSegment {
+    import implicits._
+    def apply()(implicit z: native.Zone): native.Ptr[struct_lineSegment] = native.alloc[struct_lineSegment]
+    def apply(a: native.Ptr[struct_point], b: native.Ptr[struct_point])(implicit z: native.Zone): native.Ptr[struct_lineSegment] = {
+      val ptr = native.alloc[struct_lineSegment]
+      ptr.a = a
+      ptr.b = b
+      ptr
+    }
   }
 }

docs/src/test/scala/org/scalanative/bindgen/docs/VectorSpec.scala

@@ -6,32 +6,32 @@ class VectorSpec extends FunSpec {
   describe("vector") {
     it("using generated bindings") {
       //#step-1
+      import org.example.vector._
       import scala.scalanative.native.Zone
-      import org.example.vector
-      import org.example.vector.implicits._
 
       Zone { implicit zone =>
-        val vec1p1 = struct_point()
-        val vec1p2 = struct_point()
+        val p1 = struct_point(1, 1)
+        val p2 = struct_point(7, 4)
+
+        val lineSegment1 = struct_lineSegment(p1, p2)
         //#step-1
         //#step-2
-        vec1p1.x = 0
-        vec1p1.y = 1
+        import org.example.vector.implicits._
+
+        val lineSegment2 = struct_lineSegment()
 
-        vec1p2.x = 6
-        vec1p2.y = 3
+        lineSegment2.a.x = 3
+        lineSegment2.a.y = 4
+        lineSegment2.b = struct_point(5, 0)
         //#step-2
         //#step-3
-        val vec1 = struct_vector()
-        vec1.a = vec1p1
-        vec1.b = vec1p2
+        println(cosine(lineSegment1, lineSegment2))
         //#step-3
-        val vec2 = vec1
-        //#step-4
-        val vec3 = vector.add(vec1, vec2)
-        println(s"(${vec3.a.x}, ${vec3.a.y}), (${vec3.b.x}, ${vec3.b.y})")
-        //#step-4
-        assert(vec3.a.x == vec1.a.x + vec2.a.x)
+        import org.scalactic.TolerantNumerics
+        val epsilon = 1e-3f
+        assert(
+          (0.8.toFloat === cosine(lineSegment1, lineSegment2))(
+            TolerantNumerics.tolerantFloatEquality(epsilon)))
       //#step-1
       }
       //#step-1

project/plugins.sbt

@@ -9,7 +9,7 @@ addSbtPlugin("com.eed3si9n"      % "sbt-buildinfo"              % "0.9.0")
 
 libraryDependencies += "org.scala-sbt" %% "scripted-plugin" % sbtVersion.value
 
-val VERSION = "0.3.0-RC1"
+val VERSION = "0.3.0-RC2"
 
 //#sbt-plugin-example
 addSbtPlugin("org.scala-native.bindgen" % "sbt-scala-native-bindgen" % VERSION)

tests/samples/src/test/scala/org/scalanative/bindgen/samples/StructTests.scala

@@ -60,7 +60,8 @@ object StructTests extends TestSuite {
         !anonymousStruct._1 = 'a'
         !anonymousStruct._2 = 42
 
-        val structWithAnonymousStruct = Struct.struct_structWithAnonymousStruct()
+        val structWithAnonymousStruct =
+          Struct.struct_structWithAnonymousStruct()
         structWithAnonymousStruct.anonymousStruct = anonymousStruct
 
         assert(