diff --git a/modules/41_emicapregi/AbilityToPay/realization.gms b/modules/41_emicapregi/AbilityToPay/realization.gms
index 1906f7b840b50d01313cde244ad5f7763cee234f..c6fa2500b1ceec7ed1cdcd9632ff175f4c2c2708 100644
--- a/modules/41_emicapregi/AbilityToPay/realization.gms
+++ b/modules/41_emicapregi/AbilityToPay/realization.gms
@@ -6,6 +6,9 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/AbilityToPay.gms
 
+*' @description
+*' Emission caps/permits are allocated according to the ability to pay principle  
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "declarations" $include "./modules/41_emicapregi/AbilityToPay/declarations.gms"
 $Ifi "%phase%" == "datainput" $include "./modules/41_emicapregi/AbilityToPay/datainput.gms"
diff --git a/modules/41_emicapregi/CandC/datainput.gms b/modules/41_emicapregi/CandC/datainput.gms
index 9bd775e59518eb2f0595b1ea57c74bd4a3056178..abc52a38d5d139ff3fffbe5526328232d386a21b 100644
--- a/modules/41_emicapregi/CandC/datainput.gms
+++ b/modules/41_emicapregi/CandC/datainput.gms
@@ -15,14 +15,6 @@ Execute_Loadpoint "input_ref" p41_co2eq = vm_co2eq.l;
 p41_shEmi2005(regi) = p41_co2eq("2005",regi) / sum(regi2, p41_co2eq("2005",regi2) );
 display p41_shEmi2005;
 
-*LB* safe formulation of c_polscen = 11
-$ontext
-***  contraction & convergence (reference year 2020)  +++++++++
-        p41_lambda(tall) $(tall.val<2050) = (tall.val-2020) / 30;
-        p41_lambda(tall) $(tall.val>2049) = 1;
-$offtext
-
-*gl* calculate share of global emissions according to different burden sharing rules
      pm_shPerm(t,regi) =  p41_lambda(t) * pm_pop(t,regi) / sum(regi2,pm_pop(t,regi2))
          + (1 - p41_lambda(t)) * p41_shEmi2005(regi) / sum(regi2, p41_shEmi2005(regi2));
 *** EOF ./modules/41_emicapregi/CandC/datainput.gms
diff --git a/modules/41_emicapregi/CandC/realization.gms b/modules/41_emicapregi/CandC/realization.gms
index f98e426555d0cb992618eee9137528fea7b3d6e6..8b42ff92735607950e46528bd1752d7fff75c70e 100644
--- a/modules/41_emicapregi/CandC/realization.gms
+++ b/modules/41_emicapregi/CandC/realization.gms
@@ -6,6 +6,10 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/CandC.gms
 
+*' @description
+*' Emission caps/permits are allocated according to the contraction and convergence 
+*' rule (transition towards equal per capita allocation; with reference years 2005 and 2050)
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "declarations" $include "./modules/41_emicapregi/CandC/declarations.gms"
 $Ifi "%phase%" == "datainput" $include "./modules/41_emicapregi/CandC/datainput.gms"
diff --git a/modules/41_emicapregi/GDPint/datainput.gms b/modules/41_emicapregi/GDPint/datainput.gms
index 7a500bdc85f35dfebc419c6b9c28cd8be998cacb..5fee4af62d16c6cd8f62bad7668e3776b40a9526 100644
--- a/modules/41_emicapregi/GDPint/datainput.gms
+++ b/modules/41_emicapregi/GDPint/datainput.gms
@@ -5,7 +5,8 @@
 *** |  REMIND License Exception, version 1.0 (see LICENSE file).
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/GDPint/datainput.gms
-*gl* calculate share of global emissions according to different burden sharing rules
+
+*** calculate share of global emissions 
      pm_shPerm(t,regi)  =  pm_gdp_gdx(t,regi) / sum(regi2, pm_gdp_gdx(t,regi2));
 
 
diff --git a/modules/41_emicapregi/GDPint/realization.gms b/modules/41_emicapregi/GDPint/realization.gms
index e13d093f5e782fb0429467bb347490258513d56f..3218f37a8b1f56598e8def246bd3a8475fbc8a02 100644
--- a/modules/41_emicapregi/GDPint/realization.gms
+++ b/modules/41_emicapregi/GDPint/realization.gms
@@ -6,6 +6,9 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/GDPint.gms
 
+*' @description
+*' Emission caps/permits are allocated according to GDP intensity
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "declarations" $include "./modules/41_emicapregi/GDPint/declarations.gms"
 $Ifi "%phase%" == "datainput" $include "./modules/41_emicapregi/GDPint/datainput.gms"
diff --git a/modules/41_emicapregi/POPint/datainput.gms b/modules/41_emicapregi/POPint/datainput.gms
index b0177b42307dc5defc1937a148e01b13abb1f3b1..8dbde4f1cd5b46d9041b381e66b2e5d489b4f703 100644
--- a/modules/41_emicapregi/POPint/datainput.gms
+++ b/modules/41_emicapregi/POPint/datainput.gms
@@ -5,8 +5,8 @@
 *** |  REMIND License Exception, version 1.0 (see LICENSE file).
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/POPint/datainput.gms
-*gl* calculate share of global emissions according to different burden sharing rules
-*ML* cumulated POP shares
+
+*** calculate share of global emissions 
      pm_shPerm(t,regi)  =  sum(t2, pm_pop(t2,regi))/sum((t2,regi2),pm_pop(t2,regi2));
 
 *** EOF ./modules/41_emicapregi/POPint/datainput.gms
diff --git a/modules/41_emicapregi/POPint/realization.gms b/modules/41_emicapregi/POPint/realization.gms
index aee1a59e26fc63c705a10931bb738ac9e8d0e16f..24451006f65bd2b27345db6e9ce0caf5c2706f34 100644
--- a/modules/41_emicapregi/POPint/realization.gms
+++ b/modules/41_emicapregi/POPint/realization.gms
@@ -6,6 +6,11 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/POPint.gms
 
+*' @description
+*' Emission caps/permits are allocated according to each region's share on
+*' cumulated population 
+*' 
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "declarations" $include "./modules/41_emicapregi/POPint/declarations.gms"
 $Ifi "%phase%" == "datainput" $include "./modules/41_emicapregi/POPint/datainput.gms"
diff --git a/modules/41_emicapregi/PerCapitaConvergence/datainput.gms b/modules/41_emicapregi/PerCapitaConvergence/datainput.gms
index fa0e00ec1ca45100206b033525a1550d39728cfd..abc037eee1448b4811d0163a1479806f78999ff8 100644
--- a/modules/41_emicapregi/PerCapitaConvergence/datainput.gms
+++ b/modules/41_emicapregi/PerCapitaConvergence/datainput.gms
@@ -6,7 +6,7 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/PerCapitaConvergence/datainput.gms
 
-***   contraction & convergence (reference year 2005)  +++++++++
+***   contraction & convergence (reference year 2020)  +++++++++
 p41_convergenceyear = 2050;
 p41_lambda(tall) $(tall.val < p41_convergenceyear) = (tall.val - 2020) / (p41_convergenceyear-2020);
 p41_lambda(tall) $(tall.val>2049) = 1;
@@ -21,14 +21,7 @@ display p41_shEmi2020;
 *** calculate global emissions pathway in cost-optimal scenario
 pm_emicapglob(ttot) = sum(regi, p41_co2eq(ttot,regi));
 
-*LB* safe formulation of c_polscen = 11
-$ontext
-***  contraction & convergence (reference year 2020)  +++++++++
-        p41_lambda(tall) $(tall.val<2050) = (tall.val-2020) / 30;
-        p41_lambda(tall) $(tall.val>2049) = 1;
-$offtext
-
-*gl* calculate share of global emissions according to different burden sharing rules
+*** calculate share of global emissions 
      pm_shPerm(t,regi) =  p41_lambda(t) * pm_pop(t,regi) / sum(regi2,pm_pop(t,regi2))
          + (1 - p41_lambda(t)) * p41_shEmi2020(regi) / sum(regi2, p41_shEmi2020(regi2));
 
diff --git a/modules/41_emicapregi/PerCapitaConvergence/realization.gms b/modules/41_emicapregi/PerCapitaConvergence/realization.gms
index 63e098727c4fb9231a8b29a3a185c10649428c5b..c87dddf9fa8d4b552512e863b3a59b591eca0e07 100644
--- a/modules/41_emicapregi/PerCapitaConvergence/realization.gms
+++ b/modules/41_emicapregi/PerCapitaConvergence/realization.gms
@@ -6,6 +6,10 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/PerCapitaConvergence.gms
 
+*' @description
+*' Emission caps/permits are allocated according to the contraction and convergence 
+*' rule (transition towards equal per capita allocation; with reference years 2020 and 2050)
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "declarations" $include "./modules/41_emicapregi/PerCapitaConvergence/declarations.gms"
 $Ifi "%phase%" == "datainput" $include "./modules/41_emicapregi/PerCapitaConvergence/datainput.gms"
diff --git a/modules/41_emicapregi/exog/realization.gms b/modules/41_emicapregi/exog/realization.gms
index 4cefd2b425207a9e704a566bd940c87006f16f72..1e16d3e8d8154bb05f46aa9c90411194b9e9ef40 100644
--- a/modules/41_emicapregi/exog/realization.gms
+++ b/modules/41_emicapregi/exog/realization.gms
@@ -6,6 +6,10 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/exog.gms
 
+*' @description
+*' Emission caps/permits are allocated from an exogenous emission path that have 
+*' to be provided "manually"
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "declarations" $include "./modules/41_emicapregi/exog/declarations.gms"
 $Ifi "%phase%" == "datainput" $include "./modules/41_emicapregi/exog/datainput.gms"
diff --git a/modules/41_emicapregi/module.gms b/modules/41_emicapregi/module.gms
index bb79ebc4754089cd506f724100fc76d880ff38e4..69196c2f937d4e5c6c9b179feefaabfba14a2b7a 100644
--- a/modules/41_emicapregi/module.gms
+++ b/modules/41_emicapregi/module.gms
@@ -6,6 +6,20 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/41_emicapregi.gms
 
+*' @title Regional Emission Caps 
+*'
+*' @description
+*' This module computes reginal emission caps both in absolute terms and as share of global emissions.
+*' In a setting with emissions trading these caps represent allocated permits and permit shares, respectively.
+*' The allocation of caps and permits is based on different burden sharing rules.
+
+*' @limitations
+*' Permit allocation and emissions trading yield less robust results under Nash (decentralized optimization)
+*' compared to Negishi (Social planner optimization).
+
+*' @authors Marian Leimbach, Christoph Bertram
+
+
 *###################### R SECTION START (MODULETYPES) ##########################
 $Ifi "%emicapregi%" == "AbilityToPay" $include "./modules/41_emicapregi/AbilityToPay/realization.gms"
 $Ifi "%emicapregi%" == "CandC" $include "./modules/41_emicapregi/CandC/realization.gms"
diff --git a/modules/41_emicapregi/none/realization.gms b/modules/41_emicapregi/none/realization.gms
index 519c95e74a85e9958bf4e32abc84e2905110047f..af18d75d711c2811db271c588f5d0a4298daa47a 100644
--- a/modules/41_emicapregi/none/realization.gms
+++ b/modules/41_emicapregi/none/realization.gms
@@ -6,6 +6,10 @@
 *** |  Contact: remind@pik-potsdam.de
 *** SOF ./modules/41_emicapregi/none.gms
 
+*' @description
+*' No allocation of regional emission caps/permits - applies to tax scenarios and 
+*' no-tax scenarios without permit trading  
+
 *####################### R SECTION START (PHASES) ##############################
 $Ifi "%phase%" == "datainput" $include "./modules/41_emicapregi/none/datainput.gms"
 $Ifi "%phase%" == "bounds" $include "./modules/41_emicapregi/none/bounds.gms"