From 18bd279b0c61c1267e6c23e856b6ff76aae5ca83 Mon Sep 17 00:00:00 2001 From: Cory McWilliams Date: Mon, 4 Mar 2024 12:23:00 -0500 Subject: [PATCH] Some progress on .h docs, and add a preliminary CONTRIBUTING.md. --- CONTRIBUTING.md | 36 ++++++++++++++++++++++++++++++++++++ src/bcrypt.js.h | 5 +++++ src/bip39.h | 16 ++++++++++++++++ src/bip39.words.h | 2 ++ src/database.js.h | 5 +++++ src/file.js.h | 21 +++++++++++++++++++++ 6 files changed, 85 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..e3a78ced --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,36 @@ +# Contributing to Tilde Friends +Thank you for your interest in Tilde Friends. + +Above all, Tilde Friends aims to be a fun, safe place to play. When that is at +odds with the course of development, we will work through it with respectful +communication. + +## How can I contribute? + +The nature of Tilde Friends makes for a wide range of ways to contribute + + * Just use it. Really, just kicking the tires will probably shake out issues + in useful ways at this point. + * Report and comment on bugs: https://dev.tildefriends.net/issues. + * Make apps. You don't need my permission to make and share apps with Tilde + Friends. I hope that an ecosystem of good apps grows outside of this + repository. If you want to recreate better versions of the stock apps, just + do it. If you make a better ssb app or whatever and drop me a line however + is most convenient for you, I will probably take a look and consider + replacing the stock one with it. + * Write about it. Docs in the git repository, blog posts, private messages to + me with ideas...really there is no wrong answer. Just make some noise, and + I'll do my best to incorporate or otherwise link your feedback and make the + most of it. + * Write C code in the git repository. I'm really striving for it to be the + case that other people don't really need to meddle in there, but if you can + help out, I will gladly review your pull requests via + https://dev.tildefriends.net/pulls. + +## Best practices + +* The C code is formatted with clang-format. Run `make format`. +* The rest is formatted with prettier. Run `npm run prettier`. +* We strive to have code compile on all platforms with no warnings and run with + no sanitizer issues. +* There are tests. Run `out/debug/tildefriends test`. diff --git a/src/bcrypt.js.h b/src/bcrypt.js.h index 83fb4f22..259a58e2 100644 --- a/src/bcrypt.js.h +++ b/src/bcrypt.js.h @@ -7,8 +7,13 @@ ** @{ */ +/** A JS context. */ typedef struct JSContext JSContext; +/** +** Register the bcrypt script interface. +** @param context The JS context. +*/ void tf_bcrypt_register(JSContext* context); /** @} */ diff --git a/src/bip39.h b/src/bip39.h index f7154845..60c1219e 100644 --- a/src/bip39.h +++ b/src/bip39.h @@ -11,7 +11,23 @@ #include #include +/** +** Convert a key from bytes to words. +** @param bytes A raw binary representation of a key. +** @param bytes_size The size of bytes. +** @param[out] out_words A human-readable English word representation of a key. +** @param words_size The size of the out_words buffer. +** @return True if the key was successfully converted. +*/ bool tf_bip39_bytes_to_words(const uint8_t* bytes, size_t bytes_size, char* out_words, size_t words_size); + +/** +** Convert a key from words to bytes. +** @param words A space-separated list of English words forming a key. +** @param[out] out_bytes A buffer to receive the raw binary form of the key. +** @param bytes_size The size of the out_bytes buffer. +** @return True if the key was successfully converted. +*/ bool tf_bip39_words_to_bytes(const char* words, uint8_t* out_bytes, size_t bytes_size); /** @} */ diff --git a/src/bip39.words.h b/src/bip39.words.h index 6315d313..a73a058d 100644 --- a/src/bip39.words.h +++ b/src/bip39.words.h @@ -10,6 +10,8 @@ enum { k_bip39_words_count = 2048 }; + +/** An array of words used for BIP39-encoding a key. */ extern const char* k_bip39_words[k_bip39_words_count]; /** @} */ diff --git a/src/database.js.h b/src/database.js.h index bb6cb117..9ec7c5ab 100644 --- a/src/database.js.h +++ b/src/database.js.h @@ -6,8 +6,13 @@ ** @{ */ +/** A JS context. */ typedef struct JSContext JSContext; +/** +** Register the database script interface. +** @param context The JS context. +*/ void tf_database_register(JSContext* context); /** @} */ diff --git a/src/file.js.h b/src/file.js.h index 539f5ecf..c152990e 100644 --- a/src/file.js.h +++ b/src/file.js.h @@ -8,12 +8,33 @@ #include +/** A JS context. */ typedef struct JSContext JSContext; +/** A task. */ typedef struct _tf_task_t tf_task_t; +/** +** Register the file script interface. +** @param context The JS context. +*/ void tf_file_register(JSContext* context); +/** +** Asynchronously stat() a file. +** @param task The running task. +** @param path The path to the file to stat(). +** @param callback A function that will be called with the stat result. +** @param user_data User data that will be passed to the callback. +*/ void tf_file_stat(tf_task_t* task, const char* path, void (*callback)(tf_task_t* task, const char* path, int result, const uv_stat_t* stat, void* user_data), void* user_data); + +/** +** Asynchronously read a file's contents. +** @param task The running task. +** @param path The path to the file. +** @param callback A callback that will be called with the file contents. +** @param user_data User data that will be provided to the callback. +*/ void tf_file_read(tf_task_t* task, const char* path, void (*callback)(tf_task_t* task, const char* path, int result, const void* data, void* user_data), void* user_data); /** @} */