Merge pull request #187 from scala-native/more-binding-doc-improvements

More binding doc improvements

Author: kornilova203

bindings/posix/src/main/scala/org/scalanative/bindgen/bindings/posix/regex.scala

@@ -54,6 +54,16 @@ object regex {
       def rm_eo: regoff_t = !p._2
       def rm_eo_=(value: regoff_t): Unit = !p._2 = value
     }
-    def struct_regmatch_t()(implicit z: native.Zone): native.Ptr[struct_regmatch_t] = native.alloc[struct_regmatch_t]
+  }
+
+  object struct_regmatch_t {
+    import implicits._
+    def apply()(implicit z: native.Zone): native.Ptr[struct_regmatch_t] = native.alloc[struct_regmatch_t]
+    def apply(rm_so: regoff_t, rm_eo: regoff_t)(implicit z: native.Zone): native.Ptr[struct_regmatch_t] = {
+      val ptr = native.alloc[struct_regmatch_t]
+      ptr.rm_so = rm_so
+      ptr.rm_eo = rm_eo
+      ptr
+    }
   }
 }

build.sbt

@@ -215,23 +215,30 @@ lazy val bindings = project("bindings")
 lazy val libiconv = bindingProject("iconv")
   .configure(binding("iconv.h"))
   .settings(
-    Test / nativeLinkingOptions ++= {
-      // Link with libiconv on macOS.
+    //#sbt-iconv-linking-options
+    Compile / nativeLinkingOptions ++= {
       Option(System.getProperty("os.name")) match {
         case Some("Mac OS X") => Seq("-liconv")
         case _                => Seq.empty
       }
     }
+    //#sbt-iconv-linking-options
+    ,
+    Test / nativeLinkingOptions ++= {
+      (Compile / nativeLinkingOptions).value
+    }
   )
 
-//#sbt-binding-project
+//#sbt-binding-project-multi-header
 lazy val libposix = bindingProject("posix")
   .configure(binding("fnmatch.h"))
   .configure(binding("regex.h"))
-//#sbt-binding-project
+//#sbt-binding-project-multi-header
 
+//#sbt-binding-project
 lazy val libutf8proc = bindingProject("utf8proc")
   .configure(binding("utf8proc.h", Some("utf8proc")))
+//#sbt-binding-project
 
 def project(name: String, plugged: AutoPlugin*) = {
   val unplugged = Seq(ScriptedPlugin).filterNot(plugged.toSet)

docs/src/paradox/bindings/iconv.md

@@ -1,10 +1,15 @@
-# Iconv - Character set conversion
+# iconv
+
+The [`iconv.h`] binding allows to convert text between different character sets, for example convert text from UTF-8 to ISO-8859-1.
 
 To use this binding add the following resolver and the dependency:
 
 @@binding[iconv]
 
-The [`iconv.h`] header allows to convert text between different character sets, for example UTF-8 to ISO-8859-1.
+You also need to configure your build tool to link with the iconv library on macOS.
+For sbt, you can use the following code:
+
+@@snip[sbt-iconv](../../../../build.sbt) { #sbt-iconv-linking-options }
 
 ## Example
 

docs/src/paradox/bindings/index.md

@@ -2,6 +2,8 @@
 
 The following bindings have been generated with bindgen.
 
+If you would like to contribute a binding see the @ref:[Contributing Bindings] page.
+
 @@ toc { depth=1 }
 
 @@@ index
@@ -10,4 +12,6 @@ The following bindings have been generated with bindgen.
 * [iconv](iconv.md)
 * [utf8proc](utf8proc.md)
 
-@@@
+@@@
+
+ [Contributing Bindings]: ../contrib/bindings.md

docs/src/paradox/bindings/posix.md

@@ -1,6 +1,8 @@
 # POSIX
 
-An addition to Scala Native's [POSIX](http://www.scala-native.org/en/latest/lib/posixlib.html) bindings. To use one of the POSIX bindings you must add the resolver and the dependency:
+An addition to Scala Native's [POSIX](http://www.scala-native.org/en/latest/lib/posixlib.html) bindings.
+
+To use this binding add the following resolver and dependency:
 
 @@binding[posix]
 

docs/src/paradox/bindings/utf8proc.md

@@ -1,13 +1,13 @@
-# Utf8proc - UTF-8 text processing
+# utf8proc
 
-This binding for [`utf8proc.h`] provides Unicode normalization, case-folding, and other operations for strings in the UTF-8 encoding.
+The [utf8proc] binding provides Unicode normalization, case-folding, and other operations for strings in the UTF-8 encoding.
 
-To use it add the following resolver and the dependency:
+To use this binding add the following resolver and dependency:
 
 @@binding[utf8proc]
 
 ## Example
 
 @@snip [iconv](../../../../bindings/utf8proc/src/test/scala/org/scalanative/bindgen/bindings/tests/Utf8procSpec.scala) { #usage-example }
 
- [`utf8proc.h`]: https://juliastrings.github.io/utf8proc/doc/
+ [utf8proc]: https://juliastrings.github.io/utf8proc/doc/

docs/src/paradox/contrib/bindings.md

@@ -2,10 +2,14 @@
 
 ## Adding a new Bindings
 
-To add a new binding add a new project in `build.sbt` with the name of the artifact as well as a binding configuration for each header file and optionally the library to link with. The following example shows how it is possible to generate multiple bindings per project. For most libraries a single binding should be sufficient.
+To add a new binding, add a new project in `build.sbt` with the name of the artifact as well as a binding configuration for each header file and optionally the library to link with.
 
 @@snip [build.sbt](../../../../build.sbt) { #sbt-binding-project }
 
+It is also possible to generate multiple bindings per project. For most libraries a single binding should be sufficient.
+
+@@snip [build.sbt](../../../../build.sbt) { #sbt-binding-project-multi-header }
+
 The new sbt project should also be added to the `bindings` project's list of aggregated projects.
 
 Optionally update the top-level `Dockerfile` to install the binding library's `-dev` package. 
@@ -22,16 +26,16 @@ Next, run `nativeBindgen` to generate the bindings. Note, to ensure consistency
 This can be done by running:
 
 ```sh
-docker-compose run --rm ubuntu-18.04-llvm-6.0 sbt bindings/$BINDING/nativeBindgen
+docker-compose run --rm ubuntu-18.04-llvm-6.0 sbt lib$BINDING/nativeBindgen
 ```
 
 Then write tests for the generated bindings. The test class should be in the `org.scalanative.bindgen.bindings.tests` package to make it easier to write examples for the binding documentation. Verify that the tests pass:
 
 ```sh
-docker-compose run --rm ubuntu-18.04-llvm-6.0 sbt bindings/$BINDING/test
+docker-compose run --rm ubuntu-18.04-llvm-6.0 sbt lib$BINDING/test
 ```
 
-Finally, add a page in the `bindings` folder and document the binding, ideally with an example or two of how to use it.
+Finally, add a Markdown file in the `bindings` folder and document the binding, ideally with an example or two of how to use it. Remember to add the new file to the index in `bindings/index.md`.
 
 ## Update all Bindings
 

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"
+val VERSION = "0.3.1"
 
 //#sbt-plugin-example
 addSbtPlugin("org.scala-native.bindgen" % "sbt-scala-native-bindgen" % VERSION)