Improve doccumentation

.gitignore

@@ -4,6 +4,7 @@
 
 # Conventional directory for build outputs.
 build/
+doc/
 
 # Omit committing pubspec.lock for library packages; see
 # https://dart.dev/guides/libraries/private-files#pubspeclock.

lib/constants.dart

@@ -1,3 +1,7 @@
-library lib5;
+/// Provides access to constants used by lib5.
+///
+/// Provides CID magic bytes, protocol versions, etc.
+
+library lib5.constants;
 
 export 'src/constants.dart';

lib/encryption.dart

@@ -1 +1,16 @@
+/// Uses [CryptoImplementation] to handle lib5 related encryption tasks.
+///
+/// ```dart
+/// final key = Uint8List(32); // Replace with your key
+/// final data = Uint8List.fromList([1, 2, 3, 4, 5]); // Replace with your data
+///
+/// final encryptedData = await encryptMutableBytes(data, key, crypto: s5.crypto);
+/// print('Encrypted data: $encryptedData');
+///
+/// final decryptedData = await decryptMutableBytes(encryptedData, key, crypto: crypto);
+/// print('Decrypted data: $decryptedData');
+/// ```
+
+library lib5.encryption;
+
 export 'package:lib5/src/crypto/encryption/mutable.dart';

lib/fs.dart

@@ -1,3 +1,52 @@
-library lib5;
+/// This is an experimental full FS implementation on top of S5.
+///
+/// Example usage:
+/// ```dart
+/// import 'dart:typed_data';
+///
+/// import 'package:lib5/lib5.dart';
+/// import 'package:mime/mime.dart';
+///
+/// // Initialize the API provider and user identity
+/// final String seed = "your seed here";
+/// final S5 s5 = await S5.create();
+/// await s5.recoverIdentityFromSeedPhrase(seed);
+/// await s5.registerOnNewStorageService(
+///   "https://s5.ninja",
+/// );
+/// final S5APIProvider apiProvider = s5.api;
+/// final S5UserIdentity userIdentity = s5.identity;
+///
+/// // Create a FileSystem instance
+/// final fileSystem = FileSystem(apiProvider, userIdentity);
+///
+/// // Initialize the file system
+/// await fileSystem.init();
+///
+/// // Create a directory named 'exampleDir' in the root directory
+/// await fileSystem.createDirectory('/', 'exampleDir');
+///
+/// // Create a file named 'exampleFile.txt' in the 'exampleDir' directory
+/// final fileVersion = FileVersion(
+///   ts: DateTime.now().millisecondsSinceEpoch,
+///   plaintextCID: CID.raw(Multihash.blake3(Uint8List(32))),
+/// );
+///
+/// final mediaType = lookupMimeType('exampleFile.txt');
+///
+/// await fileSystem.createFile(
+///   directoryPath: '/exampleDir',
+///   fileName: 'exampleFile.txt',
+///   fileVersion: fileVersion,
+///   mediaType: mediaType,
+/// );
+///
+/// print('Directory and file created successfully!');
+/// ```
+///
+/// The S5 FS has not been extensively tested yet, and using it directly through lib5
+/// should be approached with caution.
+
+library lib5.fs;
 
 export 'src/fs/fs.dart';

lib/identity.dart

@@ -1,4 +1,22 @@
-library lib5;
+/// Provides access to S5 identity related functions.
+///
+/// ```dart
+/// // Assuming you have a CryptoImplementation instance named 'crypto'
+/// final CryptoImplementation crypto = s5.crypto;
+
+/// // Generate a seed phrase
+/// String seedPhrase = generatePhrase(crypto: crypto);
+/// print('Generated Seed Phrase: $seedPhrase');
+
+/// // Verify the seed phrase
+/// try {
+///   Uint8List seed = validatePhrase(seedPhrase, crypto: crypto);
+///   print('Seed is valid. Seed bytes: $seed');
+/// } catch (e) {
+///   print('Seed validation failed: $e');
+/// }
+
+library lib5.identity;
 
 export 'package:lib5/src/identity/identity.dart';
 export 'package:lib5/src/seed/seed.dart';

lib/lib5.dart

@@ -1,3 +1,5 @@
+/// Provides access to all general lib5 functions.
+
 library lib5;
 
 export 'src/model/cid.dart';

lib/node.dart

@@ -1,4 +1,29 @@
-library lib5;
+/// This provides access to the self-contained S5 node.
+///
+/// Note, it is NOT recommended to initialize your own node, but to instead use the [s5](https://pub.dev/packages/s5) wrapper.
+/// Using s5.create() will generate a S5NodeBase instance without having to deal with all of this yourself.
+/// It can be embedded in any dart runtime as follows.
+/// ```dart
+/// final Map<String, dynamic> config = {config params};
+/// final Logger logger = yourlogger;
+/// final CryptoImplementation crypto;
+/// final S5NodeBase nodeBase = S5NodeBase(config: config, logger: logger, crypto: crypto);
+/// // then you need to add a KV DB
+/// if (config['database']?['path'] != null) {
+///   Hive.init(config['database']['path']);
+/// }
+/// await nodebase.init(
+///   blobDB: HiveKeyValueDB(
+///     await Hive.openBox('s5-object-cache'),
+///   ),
+///   registryDB: HiveKeyValueDB(await Hive.openBox('s5-registry-db')),
+///   streamDB: HiveKeyValueDB(await Hive.openBox('s5-stream-db')),
+///   nodesDB: HiveKeyValueDB(await Hive.openBox('s5-nodes')),
+///   p2pService: NativeP2PService(this),
+/// );
+/// ```
+
+library lib5.node;
 
 export 'src/api/node_with_identity.dart';
 export 'src/api/node.dart';
@@ -8,4 +33,4 @@ export 'src/node/service/p2p.dart';
 export 'src/node/service/registry.dart';
 export 'src/node/service/stream.dart';
 export 'src/node/store.dart';
-export 'src/node/util/uri_provider.dart';
+export 'src/node/util/uri_provider.dart';

lib/registry.dart

@@ -1,4 +1,30 @@
-library lib5;
+/// Provides access to registry functions like creating, signing, and verifying.
+///
+/// ```dart
+/// // Assuming you have a CryptoImplementation instance named 'crypto'
+/// final CryptoImplementation crypto = s5.crypto; // create s5 node earlier
+///
+/// // Generate a key pair
+/// final keyPair = await crypto.newKeyPairEd25519();
+///
+/// // Data to store in the registry entry
+/// final data = Uint8List.fromList([1, 2, 3, 4, 5]);
+/// final revision = 1;
+///
+/// // Create and sign the registry entry
+/// final entry = await SignedRegistryEntry.create(
+///   kp: keyPair,
+///   data: data,
+///   revision: revision,
+///   crypto: crypto,
+/// );
+///
+/// // Verify the signed registry entry
+/// final isValid = await entry.verify(crypto: crypto);
+///
+/// print('Registry entry is valid: $isValid');
+
+library lib5.registry;
 
 export 'src/registry/entry.dart';
 export 'src/registry/sign.dart';

lib/src/constants.dart

@@ -143,7 +143,7 @@ const metadataMediaDetailsWasLive = 12;
 const metadataProofTypeSignature = 1;
 const metadataProofTypeTimestamp = 2;
 
-// ! storage locations
+/// ! storage locations
 const storageLocationTypeArchive = 0;
 const storageLocationTypeFile = 3;
 const storageLocationTypeFull = 5;

lib/src/model/cid.dart

@@ -7,6 +7,10 @@ import 'package:lib5/src/util/endian.dart';
 import 'multibase.dart';
 import 'multihash.dart';
 
+/// CID (Content Identifier) is a compact representation of an address.
+///
+/// A CID can contain a reference to either static contents, or a registry entry (allowing
+/// for mutability). Learn more about the [CID spec here](https://docs.sfive.net/spec/blobs.html).
 class CID extends Multibase {
   late final int type;
   late final Multihash hash;

lib/storage_service.dart

@@ -1,4 +1,29 @@
-library lib5;
+/// Provides access to the storage service.
+///
+/// With these functions S5 nodes can be registered on, logged into,
+/// and worked with (for things like remote uploads).
+///
+/// ```dart
+/// final httpClient = http.Client();
+/// final storageServiceConfig = StorageServiceConfig(
+///   scheme: 'https',
+///   authority: 'example.com', // replace with node
+///   headers: {},
+/// );
+/// final apiProvider = S5APIProviderWithRemoteUpload(s5.api
+///   ..storageServiceConfigs.add(storageServiceConfig)
+///   ..httpClient = httpClient;
+///
+/// final fileData = Uint8List.fromList([/* Your file data */]);
+///
+/// try {
+///   final cid = await apiProvider.uploadBlob(fileData);
+///   print('File uploaded with CID: $cid');
+/// } catch (e) {
+///   print('File upload failed: $e');
+/// }
+
+library lib5.storage_service;
 
 export 'src/storage_service/config.dart';
 export 'src/storage_service/login.dart';

lib/util.dart

@@ -1,4 +1,6 @@
-library lib5;
+/// Provides access to basic utilities like loggers, definitions, and converters.
+
+library lib5.util;
 
 export 'src/node/logger/base.dart';
 export 'src/node/logger/simple.dart';