[jnigen] README structure doesn't provide a simple getting started flow

[stuartmorgan]

Coming to jnigen for the first time, the README didn't help me get started quickly. In general what I would want to see is an overview of what it is, enough info to get started, and then the setup and commands I need to run.

The current flow is:

• Introduction, good
• Example:

  • Java and YAML, great.

  • Dart: As a client, I want to see the Dart code I would write to use it, not the implementation. Something like 20% of the current Example section by length is literally just this function:

      static final _showToast = ProtectedJniExtensions.lookup<
          ffi.NativeFunction<
              jni.JThrowablePtr Function(
                  ffi.Pointer<ffi.Void>,
                  jni.JMethodIDPtr,
                  ffi.VarArgs<
                      (
                        ffi.Pointer<ffi.Void>,
                        ffi.Pointer<ffi.Void>,
                        ffi.Int64
                      )>)>>("globalEnv_CallStaticVoidMethod")
      .asFunction<
          jni.JThrowablePtr Function(ffi.Pointer<ffi.Void>, jni.JMethodIDPtr,
              ffi.Pointer<ffi.Void>, ffi.Pointer<ffi.Void>, int)>();

    I don't want to have to think about that function; that's why I'm using a package that generates it for me 🙂 I just want to see the magically simple code to call showToast.

• Supported platforms, Java features support, Note on Dart (standalone) target
  • This is useful info to have somewhere, but at this point I can see how it basically works from the example, so want to get started, and read details like this later (especially since "Supported platforms" and "Note on Dart (standalone)" aren't even relevant for my use case)
• Requirements
  • The mvn requirement should definitely be highlighted more prominently (and should suggest some macOS instructions like homebrew, rather than only Windows). This was the first thing I tripped over because I saw "Java tooling" and skipped it thinking that obviously I already have the Java tooling since I can already build Flutter Android apps on this machine.
  • Some clear breakout by host machine type would help too. E.g., a bulleted list with bolded entries for each host platform suggesting installation (or saying it's not needed if you already have X)
• FAQ
  • At this point my FAQ is: what command do I run if I just want to try this out 🙂 I have to scroll all the way through the FAQ to "YAML Configuration Reference" to find the first instance of actually running the command.

High level, I think swapping out what's shown for Dart in the example, and the adding a top-level "Usage" or similar right after the example that has the requirements and basic command to run would help a lot. The a lot of the caveats could move below that.

[stuartmorgan]

It would also be good to mention in the setup/usage section that the project needs to add jni. I assumed it would be a transitive dependency, so hit Fatal: package:jni was not found. almost immediately.