chore: add documentation on internal structure

packages/opentelemetry-metrics/src/export/types.ts

@@ -38,6 +38,24 @@ export interface Distribution {
 }
 
 export interface Histogram {
+  /**
+   * Buckets are implemented using two different array:
+   *  - boundaries contains every boundary (which are upper boundary for each slice)
+   *  - counts contains count of event for each slice
+   *
+   * Note that we'll always have n+1 (where n is the number of boundaries) slice
+   * because we need to count event that are above the highest boundary. This is the
+   * reason why it's not implement using array of object, because the last slice
+   * dont have any boundary.
+   *
+   * Example if we measure the values: [5, 30, 5, 40, 5, 15, 15, 15, 25]
+   *  with the boundaries [ 10, 20, 30 ], we will have the following state:
+   *
+   * buckets: {
+   *	boundaries: [10, 20, 30],
+   *	counts: [3, 3, 2, 1],
+   * }
+   */
   buckets: {
     boundaries: number[];
     counts: number[];