Clean-up comments and doc-comments

Author: xguerin

docs/examples.md

@@ -94,19 +94,17 @@ let () =
 ## Simple binary message parser
 
 ```ocaml
-(*
-  +---------------+---------------+--------------------------+
-  | type          | subtype       | parameter                |
-  +---------------+---------------+--------------------------+
-   <-- 16 bits --> <-- 16 bits --> <------- 32 bits -------->
+(* +---------------+---------------+--------------------------+
+   | type          | subtype       | parameter                |
+   +---------------+---------------+--------------------------+
+    <-- 16 bits --> <-- 16 bits --> <------- 32 bits -------->
 
-  All fields are in network byte order.
-*)
+   All fields are in network byte order. *)
 
 let%bitstring make_message typ subtype param = {|
-	typ : 16;
-	subtype : 16;
-	param : 32
+  typ : 16;
+  subtype : 16;
+  param : 32
 |};;
 ```
 

examples/elf.ml

@@ -1,18 +1,17 @@
-(* Read an ELF (Linux binary) header.
- * $Id$
- *)
+(* Read an ELF (Linux binary) header. *)
 
 open Printf
 
 let () =
   let filename = "/bin/ls" in
   let bits = Bitstring.bitstring_of_file filename in
   match%bitstring bits with
-  | {| 0x7f : 8; "ELF" : 24 : string;	(* ELF magic number *)
-      _ : 12*8 : bitstring;		(* ELF identifier *)
-      e_type : 16 : littleendian;	(* object file type *)
-      e_machine : 16 : littleendian	(* architecture *)
-    |}
+  | {| 0x7f : 8
+     ; "ELF"     : 24   : string       (* ELF magic number *)
+     ; _         : 12*8 : bitstring    (* ELF identifier *)
+     ; e_type    : 16   : littleendian (* object file type *)
+     ; e_machine : 16   : littleendian (* architecture *)
+     |}
     -> printf "%s: ELF binary, type %d, arch %d\n" filename e_type e_machine
   | {| _ |} -> eprintf "%s: Not an ELF binary\n" filename
 ;;

examples/ext3_superblock.ml

@@ -1,6 +1,4 @@
-(* Parse an ext3 superblock.
- * $Id$
- *)
+(* Parse an ext3 superblock. *)
 
 open Printf
 
@@ -12,58 +10,58 @@ let bits = Bitstring.bitstring_of_file "ext3_sb"
 
 let () =
   match%bitstring bits with
-  | {|s_inodes_count : 32 : littleendian;	(* Inodes count *)
-      s_blocks_count : 32 : littleendian;	(* Blocks count *)
-      s_r_blocks_count : 32 : littleendian;	(* Reserved blocks count *)
-      s_free_blocks_count : 32 : littleendian;	(* Free blocks count *)
-      s_free_inodes_count : 32 : littleendian;	(* Free inodes count *)
-      s_first_data_block : 32 : littleendian;	(* First Data Block *)
-      s_log_block_size : 32 : littleendian;	(* Block size *)
-      s_log_frag_size : 32 : littleendian;	(* Fragment size *)
-      s_blocks_per_group : 32 : littleendian;	(* # Blocks per group *)
-      s_frags_per_group : 32 : littleendian;	(* # Fragments per group *)
-      s_inodes_per_group : 32 : littleendian;	(* # Inodes per group *)
-      s_mtime : 32 : littleendian;		(* Mount time *)
-      s_wtime : 32 : littleendian;		(* Write time *)
-      s_mnt_count : 16 : littleendian;		(* Mount count *)
-      s_max_mnt_count : 16 : littleendian;	(* Maximal mount count *)
-      0xef53 : 16 : littleendian;		(* Magic signature *)
-      s_state : 16 : littleendian;		(* File system state *)
-      s_errors : 16 : littleendian;		(* Behaviour when detecting errors *)
-      s_minor_rev_level : 16 : littleendian;	(* minor revision level *)
-      s_lastcheck : 32 : littleendian;		(* time of last check *)
-      s_checkinterval : 32 : littleendian;	(* max. time between checks *)
-      s_creator_os : 32 : littleendian;		(* OS *)
-      s_rev_level : 32 : littleendian;		(* Revision level *)
-      s_def_resuid : 16 : littleendian;		(* Default uid for reserved blocks *)
-      s_def_resgid : 16 : littleendian;		(* Default gid for reserved blocks *)
-      s_first_ino : 32 : littleendian;		(* First non-reserved inode *)
-      s_inode_size : 16 : littleendian;		(* size of inode structure *)
-      s_block_group_nr : 16 : littleendian;	(* block group # of this superblock *)
-      s_feature_compat : 32 : littleendian;	(* compatible feature set *)
-      s_feature_incompat : 32 : littleendian;	(* incompatible feature set *)
-      s_feature_ro_compat : 32 : littleendian;	(* readonly-compatible feature set *)
-      s_uuid : 128 : string;		        (* 128-bit uuid for volume *)
-      s_volume_name : 128 : string;	        (* volume name *)
-      s_last_mounted : 512 : string;	        (* directory where last mounted *)
-      s_algorithm_usage_bitmap : 32 : littleendian; (* For compression *)
-      s_prealloc_blocks : 8;	                (* Nr of blocks to try to preallocate*)
-      s_prealloc_dir_blocks : 8;	        (* Nr to preallocate for dirs *)
-      s_reserved_gdt_blocks : 16 : littleendian;(* Per group desc for online growth *)
-      s_journal_uuid : 128 : string;	        (* uuid of journal superblock *)
-      s_journal_inum : 32 : littleendian;	(* inode number of journal file *)
-      s_journal_dev : 32 : littleendian;	(* device number of journal file *)
-      s_last_orphan : 32 : littleendian;	(* start of list of inodes to delete *)
-      s_hash_seed0 : 32 : littleendian;		(* HTREE hash seed *)
-      s_hash_seed1 : 32 : littleendian;
-      s_hash_seed2 : 32 : littleendian;
-      s_hash_seed3 : 32 : littleendian;
-      s_def_hash_version : 8;	                (* Default hash version to use *)
-      s_reserved_char_pad : 8;
-      s_reserved_word_pad : 16 : littleendian;
-      s_default_mount_opts : 32 : littleendian;
-      s_first_meta_bg : 32 : littleendian;	(* First metablock block group *)
-      _ : 6080 : bitstring |}
+  | {| s_inodes_count : 32 : littleendian           (* Inodes count *)
+     ; s_blocks_count : 32 : littleendian           (* Blocks count *)
+     ; s_r_blocks_count : 32 : littleendian         (* Reserved blocks count *)
+     ; s_free_blocks_count : 32 : littleendian      (* Free blocks count *)
+     ; s_free_inodes_count : 32 : littleendian      (* Free inodes count *)
+     ; s_first_data_block : 32 : littleendian       (* First Data Block *)
+     ; s_log_block_size : 32 : littleendian         (* Block size *)
+     ; s_log_frag_size : 32 : littleendian          (* Fragment size *)
+     ; s_blocks_per_group : 32 : littleendian       (* # Blocks per group *)
+     ; s_frags_per_group : 32 : littleendian        (* # Fragments per group *)
+     ; s_inodes_per_group : 32 : littleendian       (* # Inodes per group *)
+     ; s_mtime : 32 : littleendian                  (* Mount time *)
+     ; s_wtime : 32 : littleendian                  (* Write time *)
+     ; s_mnt_count : 16 : littleendian              (* Mount count *)
+     ; s_max_mnt_count : 16 : littleendian          (* Maximal mount count *)
+     ; 0xef53 : 16 : littleendian                   (* Magic signature *)
+     ; s_state : 16 : littleendian                  (* File system state *)
+     ; s_errors : 16 : littleendian                 (* Behaviour when detecting errors *)
+     ; s_minor_rev_level : 16 : littleendian        (* minor revision level *)
+     ; s_lastcheck : 32 : littleendian              (* time of last check *)
+     ; s_checkinterval : 32 : littleendian          (* max. time between checks *)
+     ; s_creator_os : 32 : littleendian             (* OS *)
+     ; s_rev_level : 32 : littleendian              (* Revision level *)
+     ; s_def_resuid : 16 : littleendian             (* Default uid for reserved blocks *)
+     ; s_def_resgid : 16 : littleendian             (* Default gid for reserved blocks *)
+     ; s_first_ino : 32 : littleendian              (* First non-reserved inode *)
+     ; s_inode_size : 16 : littleendian             (* size of inode structure *)
+     ; s_block_group_nr : 16 : littleendian         (* block group # of this superblock *)
+     ; s_feature_compat : 32 : littleendian         (* compatible feature set *)
+     ; s_feature_incompat : 32 : littleendian       (* incompatible feature set *)
+     ; s_feature_ro_compat : 32 : littleendian      (* readonly-compatible feature set *)
+     ; s_uuid : 128 : string                        (* 128-bit uuid for volume *)
+     ; s_volume_name : 128 : string                 (* volume name *)
+     ; s_last_mounted : 512 : string                (* directory where last mounted *)
+     ; s_algorithm_usage_bitmap : 32 : littleendian (* For compression *)
+     ; s_prealloc_blocks : 8                        (* Nr of blocks to try to preallocate*)
+     ; s_prealloc_dir_blocks : 8                    (* Nr to preallocate for dirs *)
+     ; s_reserved_gdt_blocks : 16 : littleendian    (* Per group desc for online growth *)
+     ; s_journal_uuid : 128 : string                (* uuid of journal superblock *)
+     ; s_journal_inum : 32 : littleendian           (* inode number of journal file *)
+     ; s_journal_dev : 32 : littleendian            (* device number of journal file *)
+     ; s_last_orphan : 32 : littleendian            (* start of list of inodes to delete *)
+     ; s_hash_seed0 : 32 : littleendian             (* HTREE hash seed *)
+     ; s_hash_seed1 : 32 : littleendian
+     ; s_hash_seed2 : 32 : littleendian
+     ; s_hash_seed3 : 32 : littleendian
+     ; s_def_hash_version : 8                       (* Default hash version to use *)
+     ; s_reserved_char_pad : 8
+     ; s_reserved_word_pad : 16 : littleendian
+     ; s_default_mount_opts : 32 : littleendian
+     ; s_first_meta_bg : 32 : littleendian          (* First metablock block group *)
+     ; _ : 6080 : bitstring |}
     ->
     (* Padding to the end of the block *)
     printf "ext3 superblock:\n";

examples/gif.ml

@@ -1,6 +1,4 @@
-(* GIF header parser.
- * $Id$
- *)
+(* GIF header parser. *)
 
 open Printf
 
@@ -9,15 +7,16 @@ let () =
   let filename = Sys.argv.(1) in
   let bits = Bitstring.bitstring_of_file filename in
   match%bitstring bits with
-  | {|("GIF87a"|"GIF89a") : 6*8 : string; (* GIF magic. *)
-      width : 16 : littleendian;
-      height : 16 : littleendian;
-      colormap : 1;			(* Has colormap? *)
-      colorbits : 3;			(* Color res = colorbits+1 *)
-      sortflag : 1;
-      bps : 3;				(* Bits/pixel = bps+1 *)
-      bg : 8;				(* Background colour. *)
-      aspectratio : 8|}
+  | {| ("GIF87a"|"GIF89a") : 6*8 : string       (* GIF magic. *)
+     ; width               : 16  : littleendian
+     ; height              : 16  : littleendian
+     ; colormap            : 1                  (* Has colormap? *)
+     ; colorbits           : 3                  (* Color res = colorbits+1 *)
+     ; sortflag            : 1
+     ; bps                 : 3                  (* Bits/pixel = bps+1 *)
+     ; bg                  : 8                  (* Background colour. *)
+     ; aspectratio         : 8
+     |}
     ->
     printf "%s: GIF image:\n" filename;
     printf "  size %d %d\n" width height;

examples/ipv4_header.ml

@@ -1,22 +1,27 @@
-(* Parse and display an IPv4 header from a file.
- * $Id$
- *)
+(* Parse and display an IPv4 header from a file. *)
 
 open Printf
 
 let header = Bitstring.bitstring_of_file "ipv4_header.dat"
 
 let () =
   match%bitstring header with
-  | {|version : 4; hdrlen : 4; tos : 8; length : 16;
-      identification : 16; flags : 3; fragoffset : 13;
-      ttl : 8; protocol : 8; checksum : 16;
-      source : 32;
-      dest : 32;
-      options : (hdrlen-5)*32 : bitstring;
-      payload : -1 : bitstring|}
-    when version = 4 ->
-    printf "IPv%d:\n" version;
+  | {| 4 : 4
+     ; hdrlen : 4; tos : 8
+     ; length : 16
+     ; identification : 16
+     ; flags : 3
+     ; fragoffset : 13
+     ; ttl : 8
+     ; protocol : 8
+     ; checksum : 16
+     ; source : 32
+     ; dest : 32
+     ; options : (hdrlen-5)*32 : bitstring
+     ; payload : -1 : bitstring
+     |}
+    ->
+    printf "IPv4:\n";
     printf "  header length: %d * 32 bit words\n" hdrlen;
     printf "  type of service: %d\n" tos;
     printf "  packet length: %d bytes\n" length;

examples/libpcap.ml

@@ -1,16 +1,14 @@
 (* Print out packets from a tcpdump / libpcap / wireshark capture file.
- * $Id$
- *
- * To test this, capture some data using:
- *   /usr/sbin/tcpdump -s 1500 -w /tmp/dump
- * then analyze it using:
- *   ./libpcap /tmp/dump
- *
- * The file format is documented here:
- *   http://wiki.wireshark.org/Development/LibpcapFileFormat
- *
- * libpcap endianness is determined at runtime.
- *)
+  
+   To test this, capture some data using:
+     /usr/sbin/tcpdump -s 1500 -w /tmp/dump
+   then analyze it using:
+     ./libpcap /tmp/dump
+  
+   The file format is documented here:
+     http://wiki.wireshark.org/Development/LibpcapFileFormat
+  
+   libpcap endianness is determined at runtime. *)
 
 open Printf
 
@@ -35,66 +33,67 @@ and endian_of = function
 
 and libpcap_header bits =
   match%bitstring bits with
-  | {|((0xa1b2c3d4_l|0xd4c3b2a1_l) as magic) : 32; (* magic number *)
-      major : 16 : endian (endian_of magic);	 (* version *)
-      minor : 16 : endian (endian_of magic);
-      timezone : 32 : endian (endian_of magic);	 (* timezone correction (secs)*)
-      _ : 32 : endian (endian_of magic); (* always 0 apparently *)
-      snaplen : 32 : endian (endian_of magic);	(* max length of capt pckts *)
-      network : 32 : endian (endian_of magic);	(* data link layer type *)
-      rest : -1 : bitstring
+  | {| ((0xa1b2c3d4_l|0xd4c3b2a1_l) as magic) : 32                            (* magic number *)
+     ; major                                  : 16 : endian (endian_of magic) (* version *)
+     ; minor                                  : 16 : endian (endian_of magic)
+     ; timezone                               : 32 : endian (endian_of magic) (* timezone correction (secs)*)
+     ; _                                      : 32 : endian (endian_of magic) (* always 0 apparently *)
+     ; snaplen                                : 32 : endian (endian_of magic) (* max length of capt pckts *)
+     ; network                                : 32 : endian (endian_of magic) (* data link layer type *)
+     ; rest                                   : -1 : bitstring
     |}
     -> endian_of magic, (major, minor, timezone, snaplen, network), rest
   | {|_|} -> failwith "not a libpcap/tcpdump packet capture file"
 
 and libpcap_packet e file_header bits =
   match%bitstring bits with
-  | {|ts_sec : 32 : endian (e);	(* packet timestamp seconds *)
-      ts_usec : 32 : endian (e);  (* packet timestamp microseconds *)
-      incl_len : 32 : endian (e); (* packet length saved in this file *)
-      orig_len : 32 : endian (e); (* packet length originally on wire *)
-      pkt_data : Int32.to_int incl_len*8 : bitstring;
-      rest : -1 : bitstring
-    |}
+  | {| ts_sec   : 32                      : endian (e) (* packet timestamp seconds *)
+     ; ts_usec  : 32                      : endian (e) (* packet timestamp microseconds *)
+     ; incl_len : 32                      : endian (e) (* packet length saved in this file *)
+     ; orig_len : 32                      : endian (e) (* packet length originally on wire *)
+     ; pkt_data : Int32.to_int incl_len*8 : bitstring
+     ; rest     : -1                      : bitstring
+     |}
     -> (ts_sec, ts_usec, incl_len, orig_len), pkt_data, rest
   | {|_|} -> raise End_of_file
 
 and decode_and_print_packet file_header pkt_header pkt_data =
   let ts_sec, ts_usec, _, orig_len = pkt_header in
   printf "%ld.%ld %ldB " ts_sec ts_usec orig_len;
-  (* Assume an ethernet frame containing an IPv4/6 packet.  We ignore
-   * the ethertype field and determine the IP version from the packet
-   * itself.  If it doesn't match our assumptions, hexdump it.
-   *)
+  (* Assume an ethernet frame containing an IPv4/6 packet. We ignore the
+     ethertype field and determine the IP version from the packet itself. If it
+     doesn't match our assumptions, hexdump it. *)
   (match%bitstring pkt_data with
-   | {|d0 : 8; d1 : 8; d2 : 8; d3 : 8; d4 : 8; d5 : 8; (* ether dest *)
-       s0 : 8; s1 : 8; s2 : 8; s3 : 8; s4 : 8; s5 : 8; (* ether src *)
-       _ : 16;					      (* ethertype *)
-       packet : -1 : bitstring			      (* payload *)
+   | {| d0 : 8; d1 : 8; d2 : 8; d3 : 8; d4 : 8; d5 : 8 (* ether dest *)
+      ; s0 : 8; s1 : 8; s2 : 8; s3 : 8; s4 : 8; s5 : 8 (* ether src *)
+      ; _ : 16                                         (* ethertype *)
+      ; packet : -1 : bitstring                        (* payload *)
      |}
      ->
      printf "%x:%x:%x:%x:%x:%x < %x:%x:%x:%x:%x:%x " d0 d1 d2 d3 d4 d5 s0 s1 s2 s3 s4 s5;
      (match%bitstring packet with
-      | {|4 : 4;			(* IPv4 *)
-	    hdrlen : 4; tos : 8; length : 16;
-	    identification : 16; flags : 3; fragoffset : 13;
-	    ttl : 8; protocol : 8; checksum : 16;
-	    s0 : 8; s1 : 8; s2 : 8; s3 : 8;
-	    d0 : 8; d1 : 8; d2 : 8; d3 : 8;
-	    _(*options*) : (hdrlen-5)*32 : bitstring;
-	    _(*payload*) : -1 : bitstring|}
+      | {| 4 : 4
+         ; hdrlen : 4 ; tos : 8 ; length : 16
+         ; identification : 16 ; flags : 3 ; fragoffset : 13
+         ; ttl : 8; protocol : 8; checksum : 16
+         ; s0 : 8; s1 : 8; s2 : 8; s3 : 8
+         ; d0 : 8; d1 : 8; d2 : 8; d3 : 8
+         ; _(*options*) : (hdrlen-5)*32 : bitstring
+         ; _(*payload*) : -1 : bitstring
+         |}
         -> printf "IPv4 %d.%d.%d.%d < %d.%d.%d.%d " s0 s1 s2 s3 d0 d1 d2 d3
-      | {|6 : 4;			(* IPv6 *)
-	    tclass : 8; flow : 20;
-	    length : 16; nexthdr : 8; ttl : 8;
-	    _(*source*) : 128 : bitstring;
-	    _(*dest*) : 128 : bitstring;
-	    _(*payload*) : -1 : bitstring|}
+      | {| 6 : 4
+         ; tclass : 8; flow : 20
+         ; length : 16; nexthdr : 8; ttl : 8
+         ; _(*source*) : 128 : bitstring
+         ; _(*dest*) : 128 : bitstring
+         ; _(*payload*) : -1 : bitstring
+         |}
         -> printf "IPv6 "
-      | {|_|} ->
+      | {| _ |} ->
         printf "\n";
         Bitstring.hexdump_bitstring stdout packet)
-   | {|_|} ->
+   | {| _ |} ->
      printf "\n";
      Bitstring.hexdump_bitstring stdout pkt_data);
   printf "\n"