From b845d859d179bc0e95efdeab3062099835fd3bd9 Mon Sep 17 00:00:00 2001
From: covalent <mail@lukehmcc.com>
Date: Tue, 25 Jun 2024 12:30:06 -0400
Subject: [PATCH] add API docs for s5-dart

---
 .gitignore                     |  3 +++
 lib/src/hive_key_value_db.dart |  8 ++++++++
 lib/src/logger.dart            |  2 ++
 lib/src/s5_base.dart           | 25 +++++++++++++++++++++++++
 4 files changed, 38 insertions(+)

diff --git a/.gitignore b/.gitignore
index 3cceda5..541410b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,6 @@
 # Avoid committing pubspec.lock for library packages; see
 # https://dart.dev/guides/libraries/private-files#pubspeclock.
 pubspec.lock
+
+# Created by 'dart doc'
+doc
\ No newline at end of file
diff --git a/lib/src/hive_key_value_db.dart b/lib/src/hive_key_value_db.dart
index 8ec0c97..0b5e33a 100644
--- a/lib/src/hive_key_value_db.dart
+++ b/lib/src/hive_key_value_db.dart
@@ -3,22 +3,30 @@ import 'dart:typed_data';
 import 'package:hive/hive.dart';
 import 'package:lib5/lib5.dart';
 
+/// A class built on the lib5 KV abstract. This defintion allows for simple change of KV DB in the
+/// future if needed. Currently it is built on hive.
 class HiveKeyValueDB extends KeyValueDB {
+  /// The Hive box used for KV entry and retrieval.
   final Box<Uint8List> box;
+
   HiveKeyValueDB(this.box);
 
+  /// Checks if box contains value @ key.
   @override
   bool contains(Uint8List key) => box.containsKey(String.fromCharCodes(key));
 
+  /// Gets contents of key.
   @override
   Uint8List? get(Uint8List key) => box.get(String.fromCharCodes(key));
 
+  /// Sets key to passed Uint8List data.
   @override
   void set(Uint8List key, Uint8List value) => box.put(
         String.fromCharCodes(key),
         value,
       );
 
+  /// Deletes contents @ key.
   @override
   void delete(Uint8List key) {
     box.delete(String.fromCharCodes(key));
diff --git a/lib/src/logger.dart b/lib/src/logger.dart
index bdaa3a3..1a2d616 100644
--- a/lib/src/logger.dart
+++ b/lib/src/logger.dart
@@ -1,6 +1,8 @@
 import 'package:lib5/util.dart';
 
+/// A custom logger built for S5 needs.
 class S5Logger extends SimpleLogger {
+  /// Constructor for S5Logger.
   S5Logger({
     super.prefix = '[S5] ',
     super.format = true,
diff --git a/lib/src/s5_base.dart b/lib/src/s5_base.dart
index 3cee757..3455a79 100644
--- a/lib/src/s5_base.dart
+++ b/lib/src/s5_base.dart
@@ -9,22 +9,43 @@ import 'package:lib5/util.dart';
 
 import 'hive_key_value_db.dart';
 
+/// Top level Object to access S5 related fuctions.
+///
+/// Usage:
+/// ```dart
+/// final s5 = await S5.create();
+/// ```
+///
+/// Alternatively for sync singleton creation:
+/// ```dart
+/// final s5 = S5.custom(...);
+/// ```
 class S5 {
+  /// Defines the local node.
   final S5NodeBase node;
+
+  /// API Object that can be used to access files.
   S5NodeAPI api;
 
+  /// Cyrpto impl
   CryptoImplementation get crypto => node.crypto;
 
+  /// Allows access to new S5 filesystem API.
   FileSystem get fs => FileSystem(api, identity);
 
+  /// Check if S5 node has identity set up.
   bool get hasIdentity => identity != null;
+
+  /// Define S5 node identity (can be recovered with seed).
   S5UserIdentity? identity;
   late final Box<Uint8List> _authBox;
 
+  /// Path to which Hive points to.
   static void initDataPath(String path) {
     Hive.init(path);
   }
 
+  /// Allows for custom and sync creation of an S5 singleton.
   S5.custom({
     required this.node,
     required this.api,
@@ -34,6 +55,7 @@ class S5 {
     _authBox = authBox;
   }
 
+  /// Allows for zero config creation of a S5 singleton.
   static Future<S5> create({
     Uint8List? databaseEncryptionKey,
     List<String> initialPeers = const [
@@ -109,10 +131,12 @@ class S5 {
     );
   }
 
+  /// Creates new 12 word seed, S5 specific, seed phrase String.
   String generateSeedPhrase() {
     return S5UserIdentity.generateSeedPhrase(crypto: crypto);
   }
 
+  /// Fetches user configuration (including storage services) and keys based on seed phrase.
   Future<void> recoverIdentityFromSeedPhrase(String seedPhrase) async {
     final newIdentity = await S5UserIdentity.fromSeedPhrase(
       seedPhrase,
@@ -129,6 +153,7 @@ class S5 {
     identity = newIdentity;
   }
 
+  /// Register user on new S5 node.
   Future<void> registerOnNewStorageService(String url,
       {String? inviteCode}) async {
     await (api as S5NodeAPIWithIdentity).registerAccount(