fix doc and fmts

Author: PerfectLaugh

lib/bap_demangle/bap_demangle.mli

@@ -88,9 +88,9 @@ module Std : sig
     [@@deprecated "since 2022-07 use [create] and/or [install]"]
     (** [register demangler] DEPRECATED.
 
-        @before 2.5.0 registers new demangler.
-        @after 2.5.0 no longer needed and does nothing, all demanglers
-        are automatically registered on creation. *)
+        @before 2.5.0
+          registers new demangler. after 2.5.0 no longer needed and does
+          nothing, all demanglers are automatically registered on creation. *)
 
     val lookup : ?package:string -> string -> demangler option
     (** [lookup ?package name] lookups in the registry for the demangler with

lib/bap_future/bap_future.mli

@@ -574,25 +574,33 @@ module Std : sig
 
     val foldw :
       ?stride:int -> 'a t -> int -> init:'b -> f:('b -> 'a -> 'b) -> 'b t
-    (** [foldw ss n ~init ~f] performs a windowed fold of the stream.
-        A function [f] is folded over [n] consecutive elements of [ss],
-        then the result is produced into the output stream, the window
-        is shifted by [stride] (defaults to one) and function [f]
-        applied to the next [n] elements. For example, if stream [ss]
-        produced the following sequence of elements:
+    (** [foldw ss n ~init ~f] performs a windowed fold of the stream. A function
+        [f] is folded over [n] consecutive elements of [ss], then the result is
+        produced into the output stream, the window is shifted by [stride]
+        (defaults to one) and function [f] applied to the next [n] elements. For
+        example, if stream [ss] produced the following sequence of elements:
 
-        {[1,2,3,4,5,6,7,8]}
+        {[
+          1, 2, 3, 4, 5, 6, 7, 8
+        ]}
 
-        and windows length [n] is equal to [3], then the function [f]
-        will be applied to a sequences:
-        {[[1,2,3], [2,3,4], [3,4,5], [4,5,6], [5,6,7], [6,7,8]]}.
+        and windows length [n] is equal to [3], then the function [f] will be
+        applied to a sequences:
+        {[
+          [ (1, 2, 3) ],
+          [ (2, 3, 4) ],
+          [ (3, 4, 5) ],
+          [ (4, 5, 6) ],
+          [ (5, 6, 7) ],
+          [ (6, 7, 8) ]
+        ]}
+        .
 
         Example, a moving average filter implemented with [foldw]:
 
         {[
           let moving_average ss n =
             Float.(foldw ss n ~init:zero ~f:(+) >>| fun s / of_int n)
-
         ]} *)
 
     val frame : clk:unit t -> 'a t -> init:'b -> f:('b -> 'a -> 'b) -> 'b t

lib/bap_image/bap_table.ml

@@ -70,7 +70,7 @@ let pp_elt f fmt = function
   | None -> Format.fprintf fmt "None"
   | Some (x, _) -> Format.fprintf fmt "Some %a" Addr.pp (f x)
 
-(** @pre [x <= y] *)
+(** pre [x <= y] *)
 let intersects x y = Addr.(Mem.max_addr x >= Mem.min_addr y)
 
 let prev_key map key = Map.closest_key map `Less_than key

lib/bap_sema/bap_sema_taint.ml

@@ -89,7 +89,7 @@ class context =
         {<tas = tas'>}
 
     method reg_taints r = get_taints tvs (Bil.Result.id r)
-    (** T(r) = { t : t |-> v}  *)
+    (** T(r) = [ t : t |-> v ] *)
 
     method ptr_taints r = get_taints tas r
     method all_taints = Set.union (collect_taints tvs) (collect_taints tas)

plugins/cache/bap_cache_gc.ml

@@ -1,77 +1,61 @@
-(**
-
-   The main goal is to delete files randomly and prioritizing larger files,
-   but still giving the probability for all files to be deleted.
-
-   Notation:
-   1. s(i) - the size of i-th file, where i = 0..m-1 with m being the
-      total number of files;
-   2. Sum(x(i)) = x(0) + ... x(m-1) - is the sigma operator;
-   3. T = Sum(s(i)) - the total size of the cache;
-   4. p(i) = s(i)/T - the discrete probability distrubution of the file
-      sizes in cache, likelihood that a randomly chosen file from the
-      cache will have size s(i).
-   5. F(i) = p(i) + p(i-1) + ... + p(0)
-      cumulative discrete distribution function (CDF).
-      F(i) we can generate a random number u in range 0..1,
-      using a uniform random number generator, and then find such k that
-      F(k-1) < u <= F(k).
-   6. |s| = Sum(p(i) * s(i)) = (1/T) * Sum(s(i)^2) - the expected value
-      of the size of a cache entry
-   7. |n| = t/|s| - the expected number of deletions that we need to
-      make to delete t bytes, e.g. if we want to delete half:
-      |n| = T^2 / (2*Sum(s(i)^2)
-
-   Example:
-    sizes = {4, 6, 3, 1, 6}
-    the total size of the cache is Sum(sizes(i)) = 20
-    the PDF is p(i) = {4/20; 6/20; 3/20; 1/20; 6/20}
-    and CDF is F(i) = {4/20; 10/20; 13/20; 14/20; 20/20}
-
-   We don't want to use floating points, there will be too many big and
-   small numbers and overflows and we finally want to get an
-   index. We will use rational numbers, since formulas 4. and 5. have the
-   same denominator (namely T) we can use only numenators.
-
-   On the high-level, we need to generate a random value between 0 and
-   T, and find such k that F(k-1) < S <= F(k), the k-th file will be
-   our candidate for removal. We can repeat sampling until we get |n|
-   files (of course deleting the same file twice won't free twice of
-   its size, so we had to keep in mind which files we already selected
-   and repeat until we get |n| distinct files)
-   Of course, we don't want to have a linear search for intervals, but
-   we can see, that F(i) partitions the set of sizes (0...T) into m-1
-   subsets, so we can represent F as a finite mapping, e.g., with our
-   example,
-
-   [0,3] -> 0
-   [4,9] -> 1
-   [10,12] -> 2
-   [13,13] -> 3
-   [14,19] -> 4
-
-   Since intervals are not intersecting, we don't need to use
-   Interval_map here, we just need to use the common Map from core
-   with the closest_key (`Less_or_equal_to`` function. So once we
-   generated a random size u we call for the closest_key for u and
-   pick the associated value as the index of the file that we will
-   delete. E.g., let's choose randomly a value from the range of
-   0...19, if it in range from 0..3 we will pick the first file, or if
-   it is in range from 4,9, e.g., 5, then closest_key will return 4,1,
-   so we will remove the second file. So we managed to get away from
-   ugly floats and got the desired distribution with no rounding
-   errors.
-
-   Now, after we have selected |n| distinct files we can shuffle them and
-   delete without worrying that some other process already deleted one
-   of those files. All the processes are using the same sequence of
-   pseudorandom files, so they will select approximately equal files
-   for deletion.
-
-   And finally, we don't want to make our recursive selection depend
-   from |n|, so instead of selecting |n| files for removal we will
-   select as many files as we need to remove requested size.
-*)
+(** The main goal is to delete files randomly and prioritizing larger files, but
+    still giving the probability for all files to be deleted.
+
+    Notation: 1. s(i) - the size of i-th file, where i = 0..m-1 with m being the
+    total number of files; 2. Sum(x(i)) = x(0) + ... x(m-1) - is the sigma
+    operator; 3. T = Sum(s(i)) - the total size of the cache; 4. p(i) = s(i)/T -
+    the discrete probability distrubution of the file sizes in cache, likelihood
+    that a randomly chosen file from the cache will have size s(i). 5. F(i) =
+    p(i) + p(i-1) + ... + p(0) cumulative discrete distribution function (CDF).
+    F(i) we can generate a random number u in range 0..1, using a uniform random
+    number generator, and then find such k that F(k-1) < u <= F(k). 6. |s| =
+    Sum(p(i) * s(i)) = (1/T) * Sum(s(i)^2) - the expected value of the size of a
+    cache entry 7. |n| = t/|s| - the expected number of deletions that we need
+    to make to delete t bytes, e.g. if we want to delete half: |n| = T^2 /
+    (2*Sum(s(i)^2)
+
+    Example:
+    {v
+      sizes = {4, 6, 3, 1, 6}
+      the total size of the cache is Sum(sizes(i)) = 20
+      the PDF is p(i) = {4/20; 6/20; 3/20; 1/20; 6/20}
+      and CDF is F(i) = {4/20; 10/20; 13/20; 14/20; 20/20}
+    v}
+
+    We don't want to use floating points, there will be too many big and small
+    numbers and overflows and we finally want to get an index. We will use
+    rational numbers, since formulas 4. and 5. have the same denominator (namely
+    T) we can use only numenators.
+
+    On the high-level, we need to generate a random value between 0 and T, and
+    find such k that F(k-1) < S <= F(k), the k-th file will be our candidate for
+    removal. We can repeat sampling until we get |n| files (of course deleting
+    the same file twice won't free twice of its size, so we had to keep in mind
+    which files we already selected and repeat until we get |n| distinct files)
+    Of course, we don't want to have a linear search for intervals, but we can
+    see, that F(i) partitions the set of sizes (0...T) into m-1 subsets, so we
+    can represent F as a finite mapping, e.g., with our example,
+
+    [0,3] -> 0 [4,9] -> 1 [10,12] -> 2 [13,13] -> 3 [14,19] -> 4
+
+    Since intervals are not intersecting, we don't need to use Interval_map
+    here, we just need to use the common Map from core with the closest_key
+    (`Less_or_equal_to`` function. So once we generated a random size u we call
+    for the closest_key for u and pick the associated value as the index of the
+    file that we will delete. E.g., let's choose randomly a value from the range
+    of 0...19, if it in range from 0..3 we will pick the first file, or if it is
+    in range from 4,9, e.g., 5, then closest_key will return 4,1, so we will
+    remove the second file. So we managed to get away from ugly floats and got
+    the desired distribution with no rounding errors.
+
+    Now, after we have selected |n| distinct files we can shuffle them and
+    delete without worrying that some other process already deleted one of those
+    files. All the processes are using the same sequence of pseudorandom files,
+    so they will select approximately equal files for deletion.
+
+    And finally, we don't want to make our recursive selection depend from |n|,
+    so instead of selecting |n| files for removal we will select as many files
+    as we need to remove requested size. *)
 
 open Core
 open Bap.Std

plugins/x86/x86_legacy_bil_pp.ml

@@ -1,8 +1,7 @@
 (* Copyright (C) 2017 ForAllSecure, Inc. - All Rights Reserved.*)
 (** Pretty printing
 
-    @todo Write .mli
-*)
+    TODO: Write .mli *)
 
 module Bil = X86_legacy_bil
 open Big_int_Z