Some progress on .h docs, and add a preliminary CONTRIBUTING.md.

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`.

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);
 
 /** @} */

src/bip39.h

@@ -11,7 +11,23 @@
 #include <stddef.h>
 #include <stdint.h>
 
+/**
+** 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);
 
 /** @} */

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];
 
 /** @} */

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);
 
 /** @} */

src/file.js.h

@@ -8,12 +8,33 @@
 
 #include <uv.h>
 
+/** 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);
 
 /** @} */