API docs about bdk-kotlin HOT 4 CLOSED

I took a quick look and those docs look pretty good to me. And if we go this way we can can the above commands to the build.sh script and have it stop if the docs patch fail so they can be manually fixed. In most cases we'll know the API (and related docs) are changing whenever one of the language projects updates the bdk-ffi submodule and there's a change the to the bdk.udl file.

from bdk-kotlin.

My tests have been successful, and I was able to apply the patch I had created for v0.3.2 to the new bindings file generated for v0.4.0. Not perfect (2 out of the 16 chunks could not be applied), but it was easy to fix them up manually.

_Edit: I have also applied this to the upgrade from 0.4.0 to 0.5.1 with success, while learning some things along the way (too much context lines doesn't help the patching process).

My process at this point is the following:

1. Generate the bindings file without any docs

cd bdk-ffi && uniffi-bindgen generate src/bdk.udl --no-format --out-dir ../jvm/src/main/kotlin --language kotlin && cd ..

2. Create a temp directory and copy there two copies the new bindings file

cp jvm/src/main/kotlin/org/bitcoindevkit/bdk.kt ~/temp/bdk.kt
cp jvm/src/main/kotlin/org/bitcoindevkit/bdk.kt ~/temp/bdkwithoutdocs.kt

3. Apply the patch to the first temp bindings file (dry-run first to get a sense for how the patch is going to go)

patch --dry-run --fuzz=10 ~/temp/bdk.kt docs.patch
patch --fuzz=10 ~/temp/bdk.kt docs.patch

4. Fix manually if anything could not be applied using the patch

Now you have a fully documented bdk.kt file and an undocumented file called bdkwithoutdocs.kt

5. Create new patch using the difference between the pure file and the new documented file

diff bdkwithoutdocs.kt bdk.kt --contex=20 > docs.patch

6. Move the patch file to the bdk-kotlin repo (delete the old one)

mv ~/temp/docs.patch ~/<location of your bdk-kotlin>

7. Apply the patch to both bdk.kt files in jvm and android modules

This is a last test to ensure that your patch was correctly built and is applicable to the bindings file

patch --fuzz=10 jvm/src/main/kotlin/org/bitcoindevkit/bdk.kt docs.patch
patch --fuzz=10 android/src/main/kotlin/org/bitcoindevkit/bdk.kt docs.patch

8. Generate the API docs website

./gradlew :jvm:dokkaHtml

9. Publish the website

cd ./jvm/build/dokka/html/
git init .
git add .
git commit --message "Release docs for v0.4.0"
git remote add origin https://github.com/thunderbiscuit/bdk-android-api-docs.git
git remote add origin https://github.com/thunderbiscuit/bdk-jvm-api-docs.git
git push origin master --force

10. Commit the new docs.patch

Should we commit the new bindings files? I'm not sure. It shouldn't create problems of course, but it's still playing with the bindings file, which the folks at Mozilla are very clear should be done sparingly and if possible not at all.

from bdk-kotlin.

I gave the docs for 0.4.0 for both bdk-jvm and bdk-android each a place to live (currently just their own repo so they can publish for free on github pages). This allows us to at least host them and test them while the library evolves. If everything goes well maybe we could buy domain names, but for now this is all right I think.

bdk-android: https://thunderbiscuit.github.io/bdk-android-api-docs/
bdk-jvm: https://thunderbiscuit.github.io/bdk-jvm-api-docs/

from bdk-kotlin.

fixed by #31

from bdk-kotlin.