diff --git a/lib/decoding/osmocom/coding/gsm0503_interleaving.c b/lib/decoding/osmocom/coding/gsm0503_interleaving.c
index 333e105..d5008d0 100644
--- a/lib/decoding/osmocom/coding/gsm0503_interleaving.c
+++ b/lib/decoding/osmocom/coding/gsm0503_interleaving.c
@@ -1,9 +1,12 @@
 /*
  * (C) 2013 by Andreas Eversberg <jolly@eversberg.eu>
  * (C) 2016 by Tom Tsou <tom.tsou@ettus.com>
+ * (C) 2017 by Hrald Welte <laforge@gnumonks.org>
  *
  * All Rights Reserved
  *
+ * SPDX-License-Identifier: GPL-2.0+
+ *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -23,11 +26,17 @@
 #include <string.h>
 
 #include <osmocom/core/bits.h>
-#include "gsm0503_tables.h"
-#include "gsm0503_interleaving.h"
+#include <osmocom/coding/gsm0503_tables.h>
+#include <osmocom/coding/gsm0503_interleaving.h>
 
-/*
- * GSM xCCH interleaving and burst mapping
+/*! \addtogroup interleaving
+ *  @{
+ * GSM TS 05.03 interleaving
+ *
+ * This module contains interleaving / de-interleaving routines for
+ * various channel types, as defined in 3GPP TS 05.03 / 45.003.
+ *
+ * GSM xCCH interleaving and burst mapping:
  *
  * Interleaving:
  *
@@ -46,8 +55,34 @@
  *      e(B, 58) = h_n(B)
  *
  * Where hl(B) and hn(B) are bits in burst B indicating flags.
- */
+ *
+ * GSM TCH HR/AHS interleaving and burst mapping:
+ *
+ * Interleaving:
+ *
+ * Given 288 coded input bits, form 4 blocks of 114 bits,
+ * where even bits of the first 2 blocks and odd bits of the last 2 blocks
+ * are used:
+ *
+ *      i(B, j) = c(n, k)       k = 0, ..., 227
+ *                              n = 0, ..., N, N + 1, ...
+ *                              B = B_0 + 2n + b
+ *                              j, b = table[k];
+ *
+ * Mapping on Burst:
+ *
+ *      e(B, j) = i(B, j)
+ *      e(B, 59 + j) = i(B, 57 + j)     j = 0, ..., 56
+ *      e(B, 57) = h_l(B)
+ *      e(B, 58) = h_n(B)
+ *
+ * Where hl(B) and hn(B) are bits in burst B indicating flags.
+ *
+ * \file gsm0503_interleaving.c */
 
+/*! De-Interleave burst bits according to TS 05.03 4.1.4
+ *  \param[out] cB caller-allocated output buffer for 456 soft coded bits
+ *  \param[in] iB 456 soft input bits */
 void gsm0503_xcch_deinterleave(sbit_t *cB, const sbit_t *iB)
 {
 	int j, k, B;
@@ -59,7 +94,10 @@
 	}
 }
 
-void gsm0503_xcch_interleave(ubit_t *cB, ubit_t *iB)
+/*! Interleave burst bits according to TS 05.03 4.1.4
+ *  \param[out] iB caller-allocated output buffer for 456 soft interleaved bits
+ *  \param[in] cB 456 soft input coded bits */
+void gsm0503_xcch_interleave(const ubit_t *cB, ubit_t *iB)
 {
 	int j, k, B;
 
@@ -70,6 +108,11 @@
 	}
 }
 
+/*! De-Interleave MCS1 DL burst bits according to TS 05.03 5.1.5.1.5
+ *  \param[out] u caller-allocated output buffer for 12 soft coded bits
+ *  \param[out] hc caller-allocated output buffer for 68 soft coded bits
+ *  \param[out] dc caller-allocated output buffer for 372 soft coded bits
+ *  \param[in] iB 452 interleaved soft input bits */
 void gsm0503_mcs1_dl_deinterleave(sbit_t *u, sbit_t *hc,
 	sbit_t *dc, const sbit_t *iB)
 {
@@ -106,6 +149,11 @@
 	}
 }
 
+/*! Interleave MCS1 DL burst bits according to TS 05.03 5.1.5.1.5
+ *  \param[in] up 12 input soft coded bits (usf)
+ *  \param[in] hc 68 input soft coded bits (header)
+ *  \param[in] dc 372 input soft bits (data)
+ *  \param[out] iB 456 interleaved soft output bits */
 void gsm0503_mcs1_dl_interleave(const ubit_t *up, const ubit_t *hc,
 	const ubit_t *dc, ubit_t *iB)
 {
@@ -139,6 +187,10 @@
 	gsm0503_xcch_interleave(cp, iB);
 }
 
+/*! Interleave MCS1 UL burst bits according to TS 05.03 5.1.5.2.4
+ *  \param[out] hc caller-allocated output buffer for 80 soft coded header bits
+ *  \param[out] dc caller-allocated output buffer for 372 soft coded data bits
+ *  \param[in] iB 456 interleaved soft input bits */
 void gsm0503_mcs1_ul_deinterleave(sbit_t *hc, sbit_t *dc, const sbit_t *iB)
 {
 	int k;
@@ -169,6 +221,10 @@
 	}
 }
 
+/*! Interleave MCS1 DL burst bits according to TS 05.03 5.1.5.2.4
+ *  \param[in] hc 80 input coded bits (header)
+ *  \param[in] dc 372 input bits (data)
+ *  \param[out] iB 456 interleaved output bits */
 void gsm0503_mcs1_ul_interleave(const ubit_t *hc, const ubit_t *dc, ubit_t *iB)
 {
 	int k;
@@ -199,6 +255,11 @@
 	gsm0503_xcch_interleave(cp, iB);
 }
 
+/*! Interleave MCS5 UL burst bits according to TS 05.03 5.1.9.2.4
+ *  \param[in] hc 136 soft coded header input bits
+ *  \param[in] dc 1248 soft coded data input bits
+ *  \param[out] hi 136 interleaved header output bits
+ *  \param[out] di 1248 interleaved data output bits */
 void gsm0503_mcs5_ul_interleave(const ubit_t *hc, const ubit_t *dc,
 	ubit_t *hi, ubit_t *di)
 {
@@ -217,6 +278,10 @@
 	}
 }
 
+/*! De-Interleave MCS5 UL burst bits according to TS 05.03 5.1.9.2.4
+ *  \param[out] hc caller-allocated output buffer for 136 soft coded header bits
+ *  \param[out] dc caller-allocated output buffer for 1248 soft coded data bits
+ *  \param[in] iB interleaved soft input bits */
 void gsm0503_mcs5_ul_deinterleave(sbit_t *hc, sbit_t *dc,
 	const sbit_t *hi, const sbit_t *di)
 {
@@ -239,6 +304,11 @@
 	}
 }
 
+/*! Interleave MCS5 DL burst bits according to TS 05.03 5.1.9.1.5
+ *  \param[in] hc 100 soft coded header input bits
+ *  \param[in] dc 1248 soft coded data input bits
+ *  \param[out] hi 100 interleaved header output bits
+ *  \param[out] di 1248 interleaved data output bits */
 void gsm0503_mcs5_dl_interleave(const ubit_t *hc, const ubit_t *dc,
 	ubit_t *hi, ubit_t *di)
 {
@@ -257,6 +327,10 @@
 	}
 }
 
+/*! De-Interleave MCS5 UL burst bits according to TS 05.03 5.1.9.1.5
+ *  \param[out] hc caller-allocated output buffer for 100 soft coded header bits
+ *  \param[out] dc caller-allocated output buffer for 1248 soft coded data bits
+ *  \param[in] iB interleaved soft input bits */
 void gsm0503_mcs5_dl_deinterleave(sbit_t *hc, sbit_t *dc,
 	const sbit_t *hi, const sbit_t *di)
 {
@@ -279,6 +353,12 @@
 	}
 }
 
+/*! Interleave MCS7 DL burst bits according to TS 05.03 5.1.11.1.5
+ *  \param[in] hc 124 soft coded header input bits
+ *  \param[in] c1 612 soft coded data input bits
+ *  \param[in] c2 612 soft coded data input bits
+ *  \param[out] hi 124 interleaved header output bits
+ *  \param[out] di 1224 interleaved data output bits */
 void gsm0503_mcs7_dl_interleave(const ubit_t *hc, const ubit_t *c1,
 	const ubit_t *c2, ubit_t *hi, ubit_t *di)
 {
@@ -302,7 +382,12 @@
 	}
 }
 
-
+/*! De-Interleave MCS7 DL burst bits according to TS 05.03 5.1.11.1.5
+ *  \param[out] hc caller-allocated output buffer for 124 soft coded header bits
+ *  \param[out] c1 caller-allocated output buffer for 612 soft coded data bits
+ *  \param[out] c2 caller-allocated output buffer for 612 soft coded data bits
+ *  \param[in] hi interleaved soft input header bits
+ *  \param[in] di interleaved soft input data bits */
 void gsm0503_mcs7_dl_deinterleave(sbit_t *hc, sbit_t *c1, sbit_t *c2,
 	const sbit_t *hi, const sbit_t *di)
 {
@@ -330,6 +415,12 @@
 	}
 }
 
+/*! Interleave MCS7 UL burst bits according to TS 05.03 5.1.11.2.4
+ *  \param[in] hc 124 soft coded header input bits
+ *  \param[in] c1 612 soft coded data input bits
+ *  \param[in] c2 612 soft coded data input bits
+ *  \param[out] hi 124 interleaved header output bits
+ *  \param[out] di 1224 interleaved data output bits */
 void gsm0503_mcs7_ul_interleave(const ubit_t *hc, const ubit_t *c1,
 	const ubit_t *c2, ubit_t *hi, ubit_t *di)
 {
@@ -353,6 +444,12 @@
 	}
 }
 
+/*! De-Interleave MCS7 UL burst bits according to TS 05.03 5.1.11.2.4
+ *  \param[out] hc caller-allocated output buffer for 160 soft coded header bits
+ *  \param[out] c1 caller-allocated output buffer for 612 soft coded data bits
+ *  \param[out] c2 caller-allocated output buffer for 612 soft coded data bits
+ *  \param[in] hi interleaved soft input header bits
+ *  \param[in] di interleaved soft input data bits */
 void gsm0503_mcs7_ul_deinterleave(sbit_t *hc, sbit_t *c1, sbit_t *c2,
 	const sbit_t *hi, const sbit_t *di)
 {
@@ -380,6 +477,12 @@
 	}
 }
 
+/*! Interleave MCS8 UL burst bits according to TS 05.03 5.1.12.2.4
+ *  \param[in] hc 160 soft coded header input bits
+ *  \param[in] c1 612 soft coded data input bits
+ *  \param[in] c2 612 soft coded data input bits
+ *  \param[out] hi 160 interleaved header output bits
+ *  \param[out] di 1224 interleaved data output bits */
 void gsm0503_mcs8_ul_interleave(const ubit_t *hc, const ubit_t *c1,
 	const ubit_t *c2, ubit_t *hi, ubit_t *di)
 {
@@ -403,6 +506,13 @@
 	}
 }
 
+
+/*! De-Interleave MCS8 UL burst bits according to TS 05.03 5.1.12.2.4
+ *  \param[out] hc caller-allocated output buffer for 160 soft coded header bits
+ *  \param[out] c1 caller-allocated output buffer for 612 soft coded data bits
+ *  \param[out] c2 caller-allocated output buffer for 612 soft coded data bits
+ *  \param[in] hi interleaved soft input header bits
+ *  \param[in] di interleaved soft input data bits */
 void gsm0503_mcs8_ul_deinterleave(sbit_t *hc, sbit_t *c1, sbit_t *c2,
 	const sbit_t *hi, const sbit_t *di)
 {
@@ -430,6 +540,12 @@
 	}
 }
 
+/*! Interleave MCS8 DL burst bits according to TS 05.03 5.1.12.1.5
+ *  \param[in] hc 124 soft coded header input bits
+ *  \param[in] c1 612 soft coded data input bits
+ *  \param[in] c2 612 soft coded data input bits
+ *  \param[out] hi 124 interleaved header output bits
+ *  \param[out] di 1224 interleaved data output bits */
 void gsm0503_mcs8_dl_interleave(const ubit_t *hc, const ubit_t *c1,
 	const ubit_t *c2, ubit_t *hi, ubit_t *di)
 {
@@ -453,6 +569,12 @@
 	}
 }
 
+/*! De-Interleave MCS8 DL burst bits according to TS 05.03 5.1.12.1.5
+ *  \param[out] hc caller-allocated output buffer for 124 soft coded header bits
+ *  \param[out] c1 caller-allocated output buffer for 612 soft coded data bits
+ *  \param[out] c2 caller-allocated output buffer for 612 soft coded data bits
+ *  \param[in] hi interleaved soft input header bits
+ *  \param[in] di interleaved soft input data bits */
 void gsm0503_mcs8_dl_deinterleave(sbit_t *hc, sbit_t *c1, sbit_t *c2,
 	const sbit_t *hi, const sbit_t *di)
 {
@@ -504,7 +626,10 @@
  * Where hl(B) and hn(B) are bits in burst B indicating flags.
  */
 
-void gsm0503_tch_fr_deinterleave(sbit_t *cB, sbit_t *iB)
+/*! GSM TCH FR/EFR/AFS De-Interleaving and burst mapping
+ *  \param[out] cB caller-allocated buffer for 456 unpacked output bits
+ *  \param[in] iB 456 unpacked interleaved input bits */
+void gsm0503_tch_fr_deinterleave(sbit_t *cB, const sbit_t *iB)
 {
 	int j, k, B;
 
@@ -515,7 +640,10 @@
 	}
 }
 
-void gsm0503_tch_fr_interleave(ubit_t *cB, ubit_t *iB)
+/*! GSM TCH FR/EFR/AFS Interleaving and burst mapping
+ *  \param[in] cB caller-allocated buffer for 456 unpacked input bits
+ *  \param[out] iB 456 unpacked interleaved output bits */
+void gsm0503_tch_fr_interleave(const ubit_t *cB, ubit_t *iB)
 {
 	int j, k, B;
 
@@ -526,31 +654,10 @@
 	}
 }
 
-/*
- * GSM TCH HR/AHS interleaving and burst mapping
- *
- * Interleaving:
- *
- * Given 288 coded input bits, form 4 blocks of 114 bits,
- * where even bits of the first 2 blocks and odd bits of the last 2 blocks
- * are used:
- *
- *      i(B, j) = c(n, k)       k = 0, ..., 227
- *                              n = 0, ..., N, N + 1, ...
- *                              B = B_0 + 2n + b
- *                              j, b = table[k];
- *
- * Mapping on Burst:
- *
- *      e(B, j) = i(B, j)
- *      e(B, 59 + j) = i(B, 57 + j)     j = 0, ..., 56
- *      e(B, 57) = h_l(B)
- *      e(B, 58) = h_n(B)
- *
- * Where hl(B) and hn(B) are bits in burst B indicating flags.
- */
-
-void gsm0503_tch_hr_deinterleave(sbit_t *cB, sbit_t *iB)
+/*! GSM TCH HR/AHS De-Interleaving and burst mapping
+ *  \param[out] cB caller-allocated buffer for 228 unpacked output bits
+ *  \param[in] iB 228 unpacked interleaved input bits */
+void gsm0503_tch_hr_deinterleave(sbit_t *cB, const sbit_t *iB)
 {
 	int j, k, B;
 
@@ -561,7 +668,10 @@
 	}
 }
 
-void gsm0503_tch_hr_interleave(ubit_t *cB, ubit_t *iB)
+/*! GSM TCH HR/AHS Interleaving and burst mapping
+ *  \param[in] cB caller-allocated buffer for 228 unpacked input bits
+ *  \param[out] iB 228 unpacked interleaved output bits */
+void gsm0503_tch_hr_interleave(const ubit_t *cB, ubit_t *iB)
 {
 	int j, k, B;
 
@@ -571,3 +681,5 @@
 		iB[B * 114 + j] = cB[k];
 	}
 }
+
+/*! @} */