Update documentation

- Document raised exceptions
- Update README.md:
  - Update the example to the changed interface
  - Explain more
  - mirage-block-partition-mbr

README.md

@@ -1,8 +1,8 @@
-## mirage-block-partition -- naïve block device partitioning
+## mirage-block-partition -- block device partitioning
 
 Mirage-block-partition lets you view a mirage block device as smaller partitions.
-
-
+The interface is structured around (successively) partitioning into two smaller partitions.
+The reason for this at times perhaps slightly inconvenient interface is it makes it harder to accidentally construct overlapping partitions.
 
 ```OCaml
 module Make(B : Mirage_block.S)(Clock : Mirage_clock.PCLOCK) = struct
@@ -13,23 +13,22 @@ module Make(B : Mirage_block.S)(Clock : Mirage_clock.PCLOCK) = struct
 
   let start b =
     let open Lwt.Syntax in
-    let* r =
-      let open Lwt_result.Syntax in
-      (* b1 is the first kilobyte, b2 is the next 4 MiB,
-         and b3 is the remaining space *)
-      let* b1, rest = Partitioned.connect 1024 in
-      let+ b2, b3 = Partitioned.subpartition 0x400000 rest in
-      b1, b2, b3
-    in
-    match r with
-    | Error e ->
-      Lwt.fail_with (Fmt.str "partition error: %a" Partitioned.pp_error e)
-    | Ok (b1, b2, b3) ->
-      (* now use e.g. b1 as a tar KV store, b2 as a chamelon filesystem,
-         b3 as a raw block device... *)
-      let* tar = Tar.connect b1
-      and* chamelon = Chamelon.connect ~program_size:16 b2 in
-      ...
+    (* b1 is the first twenty sectors, b2 is the next 8k sectors (4 MiB),
+       and b3 is the remaining space. Note that the initial [connect] call is
+       asynchronous while the later [subpartition] calls are not. If the
+       partition point is outside the block device or subpartition then an
+       exception is raised. *)
+    let* b1, rest = Partitioned.connect 20L b in
+    let b2, b3 = Partitioned.subpartition 8192L rest in
+    (* now use e.g. b1 as a tar KV store, b2 as a chamelon filesystem,
+       b3 as a raw block device... *)
+    let* tar = Tar.connect b1
+    and* chamelon = Chamelon.connect ~program_size:16 b2 in
+    ...
 
 end
 ```
+
+### mirage-block-partition-mbr
+
+This module reads a disk labeled with a Master Boot Record and returns a list of pairs of `Mbr.Partition.t` and a block device representing the partition according to the MBR.

lib/mirage_block_partition.mli

@@ -5,11 +5,13 @@ module Make(B : Mirage_block.S) : sig
   (** [connect first_sectors b] returns two block device partitions of b with
       the first partition of [first_sectors] sectors, and the second partition
       the remaining space, if any.
+      @raises Invalid_argument if the partition point is outside the device.
   *)
 
   val subpartition : int64 -> t -> (t * t)
   (** [subpartition first_sectors b] further partitions a partition into two sub
       partitions.
+      @raises Invalid_argument if the partition point is outside the partition.
   *)
 
   val get_offset : t -> int64

lib/mirage_block_partition_mbr.mli

@@ -1,4 +1,9 @@
 module Make(B : Mirage_block.S) : sig
   include Mirage_block.S
   val connect : B.t -> ((Mbr.Partition.t * t) list, [ `Overlapping_partitions ]) result Lwt.t
+  (** [connect b] returns a pair of [Mbr.Partition.t] from the MBR and a
+      corresponding device representing the partition. An error is returned if
+      any of the partitions overlap.
+      @raise Invalid_argument if the the sector size of [b] is not exactly 512 bytes or if any of the partitions are outsie the device.
+      @raise Failure if reading the MBR fails or does not parse. *)
 end