minor updates and improvements to documentation: (#40)

- fix some small formatting issues in cli-usage.md - add task of creating a PR in conan-center-index to release instructions in developer-guide.md - improve generated-code-usage.md by mentioning the support-lib instead of telling the user to add the support-lib sourcefiles to his target manually. - Improve explanation of djinni_main.cpp in generated-code-usage.md
cross-language-cpp · Apr 7, 2021 · 844c1b6 · 844c1b6
1 parent ab31452
commit 844c1b6
Show file tree

Hide file tree

Showing 3 changed files with 36 additions and 26 deletions.
diff --git a/docs/cli-usage.md b/docs/cli-usage.md
@@ -37,7 +37,7 @@ djinni \
 | `--help` | Print help  |
 | `--version` | Print version |
 | `--idl <in-file>` | The IDL file with the type definitions, typically with extension `.djinni`. |
-| `--idl-include-path <path> ...` | An include path to search for Djinni @import directives. Can specify multiple paths. |
+| `--idl-include-path <path> ...` | An include path to search for Djinni `@import` directives. Can specify multiple paths. |
 
 ### Java
 | Argument | Description |
@@ -50,7 +50,7 @@ djinni \
 | `--java-generate-interfaces <true/false>` | Whether Java interfaces should be used instead of abstract classes where possible (default: `false`). |
 | `--java-nullable-annotation <nullable-annotation-class>` | Java annotation (`@Nullable`) to place on all fields and return values that are optional |
 | `--java-nonnull-annotation <nonnull-annotation-class>` | Java annotation (`@Nonnull`) to place on all fields and return values that are not optional |
-| `--java-implement-android-os-parcelable <true/false>` | all generated java classes will implement the interface android.os.Parcelable |
+| `--java-implement-android-os-parcelable <true/false>` | all generated java classes will implement the interface `android.os.Parcelable` |
 | `--java-use-final-for-record <use-final-for-record>` | Whether generated Java classes for records should be marked `final` (default: `true`). |
 
 ### C++
@@ -59,13 +59,13 @@ djinni \
 | -------- | ----------- |
 | `--cpp-out <out-folder>` | The output folder for C++ files (Generator disabled if unspecified). |
 | `--cpp-header-out <out-folder>` | The output folder for C++ header files (default: the same as `--cpp-out`). |
-| `--cpp-include-prefix <prefix>` | The prefix for #includes of header files from C++ files. |
+| `--cpp-include-prefix <prefix>` | The prefix for `#includes` of header files from C++ files. |
 | `--cpp-namespace ...` | The namespace name to use for generated C++ classes. |
 | `--cpp-ext <ext>` | The filename extension for C++ files (default: `cpp`). |
 | `--hpp-ext <ext>` | The filename extension for C++ header files (default: `hpp`). |
 | `--cpp-optional-template <template>` | The template to use for optional values (default: `std::optional`) |
 | `--cpp-optional-header <header>` | The header to use for optional values (default: `<optional>`) |
-| `--cpp-enum-hash-workaround <true/false>` | Work around LWG-2148 by generating std::hash specializations for C++ enums (default: `true`) |
+| `--cpp-enum-hash-workaround <true/false>` | Work around LWG-2148 by generating `std::hash` specializations for C++ enums (default: `true`) |
 | `--cpp-nn-header <header>` | The header to use for non-nullable pointers |
 | `--cpp-nn-type <header>` | The type to use for non-nullable pointers (as a substitute for `std::shared_ptr`) |
 | `--cpp-nn-check-expression <header>` | The expression to use for building non-nullable pointers |
@@ -77,8 +77,8 @@ djinni \
 | -------- | ----------- |
 | `--jni-out <out-folder>` | The folder for the JNI C++ output files (Generator disabled if unspecified). |
 | `--jni-header-out <out-folder>` | The folder for the JNI C++ header files (default: the same as `--jni-out`). |
-| `--jni-include-prefix <prefix>` | The prefix for #includes of JNI header files from JNI C++ files. |
-| `--jni-include-cpp-prefix <prefix>` | The prefix for #includes of the main header files from JNI C++ files. |
+| `--jni-include-prefix <prefix>` | The prefix for `#includes` of JNI header files from JNI C++ files. |
+| `--jni-include-cpp-prefix <prefix>` | The prefix for `#includes` of the main header files from JNI C++ files. |
 | `--jni-namespace ...` | The namespace name to use for generated JNI C++ classes. |
 | `--jni-base-lib-include-prefix ...` | The JNI base support library's include path (default: `djinni/jni/`). |
 
@@ -90,9 +90,9 @@ djinni \
 | `--objc-header-out <out-folder>` | The output folder for Objective-C header files (default: the same as `--objc-out`). |
 | `--objc-h-ext <ext>` | The filename extension for Objective-C[++] header files (default: `h`) |
 | `--objc-type-prefix <pre>` | The prefix for Objective-C data types (usually two or three letters) |
-| `--objc-include-prefix <prefix>` | The prefix for #import of header files from Objective-C files. |
+| `--objc-include-prefix <prefix>` | The prefix for `#import` of header files from Objective-C files. |
 | `--objc-swift-bridging-header <name>` | The name of Objective-C Bridging Header used in XCode's Swift projects. The output folder is `--objc-header-out`. |
-| `--objc-closed-enums <true/false>` | All generated Objective-C enums will be NS_CLOSED_ENUM (default: `false`). |
+| `--objc-closed-enums <true/false>` | All generated Objective-C enums will be `NS_CLOSED_ENUM` (default: `false`). |
 
 ### Objective-C++
 
@@ -101,10 +101,10 @@ djinni \
 | `--objcpp-out <out-folder>` | The output folder for private Objective-C++ files (Generator disabled if unspecified). |
 | `--objcpp-ext <ext>` | The filename extension for Objective-C++ files (default: `mm`) |
 | `--objcpp-include-prefix <prefix>` | The prefix for #import of Objective-C++ header files from Objective-C++ files. |
-| `--objcpp-include-cpp-prefix <prefix>` | The prefix for #include of the main C++ header files from Objective-C++ files. |
-| `--objcpp-include-objc-prefix <prefix>` | The prefix for #import of the Objective-C header files from Objective-C++ files (default: the same as `--objcpp-include-prefix`) |
-| `--cpp-extended-record-include-prefix <prefix>` | The prefix path for #include of the extended record C++ header (`.hpp`) files |
-|`--objc-extended-record-include-prefix <prefix>` | The prefix path for #import of the extended record Objective-C header (`.h`) files  |
+| `--objcpp-include-cpp-prefix <prefix>` | The prefix for `#include` of the main C++ header files from Objective-C++ files. |
+| `--objcpp-include-objc-prefix <prefix>` | The prefix for `#import` of the Objective-C header files from Objective-C++ files (default: the same as `--objcpp-include-prefix`) |
+| `--cpp-extended-record-include-prefix <prefix>` | The prefix path for `#include` of the extended record C++ header (`.hpp`) files |
+|`--objc-extended-record-include-prefix <prefix>` | The prefix path for `#import` of the extended record Objective-C header (`.h`) files  |
 |`--objcpp-namespace <prefix>` | The namespace name to use for generated Objective-C++ classes.  |
 |`--objc-base-lib-include-prefix ...` | The Objective-C base support library's include path (default: `djinni/objc/`).  |
 

diff --git a/docs/developer-guide.md b/docs/developer-guide.md
@@ -42,7 +42,7 @@ sbt "run
 sbt "run --help"  # show all options
 ```
 
-*It is important to put `run` and all arguments in `"`, to be able to pass arguments to the executed jar*
+*It is important to put `run` and all arguments in `"`, to be able to pass arguments to the executed jar!*
 
 ### Running Tests
 
@@ -59,7 +59,7 @@ sbt assembly
 ```
 
 This will generate a standalone, self-executing jar in `target/bin`.
-You can run the jar like this (no need for `java -jar`):
+You can run the jar like this:
 
 ```bash
 ./djinni --help
@@ -69,7 +69,7 @@ On Windows the file must be renamed to `djinni.bat` to make it executable.
 
 !!! attention
 
-    The resulting binary still requires Java to able to run! [Details on how the self-executing jar works](https://github.com/sbt/sbt-assembly#prepending-a-launch-script).
+    The resulting binary still requires Java to be able to run! [Details on how the self-executing jar works](https://github.com/sbt/sbt-assembly#prepending-a-launch-script).
 
 ## Project Structure
 
@@ -119,5 +119,6 @@ On Windows the file must be renamed to `djinni.bat` to make it executable.
 
 To release a new version of the generator, the following steps must be followed:
 
-1. Create a new release-tag. Set a meaningful version number and describe what has changed in the new version.
-2. Wait. Github will automatically build the project and upload the resulting binaries to the release.
+1. Create a [new release](https://github.com/cross-language-cpp/djinni-generator/releases/new) on Github. Set a tag version following [semantic versioning](https://semver.org/) rules (`v<MAJOR>.<MINOR>.<PATCH>`) and describe what has changed in the new version.
+2. Wait. The [Github "release" Action](https://github.com/cross-language-cpp/djinni-generator/blob/main/.github/workflows/release.yaml) will automatically build the project and upload the resulting binaries to the release.
+3. Create a PR to the [conan-center-index](https://github.com/conan-io/conan-center-index/tree/master/recipes/djinni-generator) to publish the new version to [Conan Center](https://conan.io/center/djinni-generator).
diff --git a/docs/generated-code-usage.md b/docs/generated-code-usage.md
@@ -13,8 +13,7 @@ The following headers / code will be generated for each defined type:
 
 (+) Generated only for types that contain constants.
 
-Add all generated source files to your build target, as well as the contents of
-`support-lib/java`.
+Add all generated source files to your build target, and link the C++ code against the [djinni-support-lib](https://github.com/cross-language-cpp/djinni-support-lib).
 
 ### Our JNI approach
 JNI stands for [Java Native Interface](http://docs.oracle.com/javase/6/docs/technotes/guides/jni/spec/jniTOC.html), an extension of the Java language to allow interop with
@@ -27,16 +26,25 @@ class with a `toJava` and `fromJava` function to translate back and forth.
 Application code is responsible for the initial load of the JNI library. Add a static block
 somewhere in your code:
 
-    System.loadLibrary("YourLibraryName");
-    // The name is specified in Android.mk / build.gradle / Makefile, depending on your build system.
+```java
+class Main {
+    static {
+      System.loadLibrary("YourLibraryName");
+      // The name  of the library is specified in Android.mk / build.gradle / Makefile / CMakeLists.txt, 
+      // depending on your build system.
+    }
+}
+```
 
 If you package your native library in a jar, you can also use the [`NativeLibLoader`](https://github.com/cross-language-cpp/djinni-support-lib/blob/main/java/com/dropbox/djinni/NativeLibLoader.java)
 to help unpack and load your lib(s).
 
-When a native library is called, JNI calls a special function called `JNI_OnLoad`. If you use
-Djinni for all JNI interface code, include `support_lib/jni/djinni_main.cpp`; if not,
-you'll need to add calls to your own `JNI_OnLoad` and `JNI_OnUnload` functions. See
-`support-lib/jni/djinni_main.cpp` for details.
+When a native library is called, JNI calls a special function called [`JNI_OnLoad`](https://github.com/cross-language-cpp/djinni-support-lib/blob/main/djinni/jni/djinni_main.cpp#L23).
+
+If your app doesn't use JNI except through Djinni, include [`djinni/jni/djinni_main.cpp`](https://github.com/cross-language-cpp/djinni-support-lib/blob/main/djinni/jni/djinni_main.cpp). 
+It defines default `JNI_Onload` and `JNI_OnUnload` functions for Djinni.
+
+If your app also includes a non-Djinni JNI interface, you'll need to define your own `JNI_OnLoad` and `JNI_OnUnload` functions.
 
 ## Objective-C / C++ Project
 
@@ -54,5 +62,6 @@ Generated files for Objective-C / C++ are as follows (assuming prefix is `DB`):
 - :one: Generated only for types that contain constants.
 - :two: Generated only for types with derived operations and/or constants. These have `.mm` extensions to allow non-trivial constants.
 
-Add all generated files to your build target, as well as the contents of `support-lib/objc`.
+Add all generated files to your build target, and link against the [djinni-support-lib](https://github.com/cross-language-cpp/djinni-support-lib).
+
 Note that `+Private` files can only be used with ObjC++ source (other headers are pure ObjC) and are not required by Objective-C users of your interface.