diff --git a/CMakeLists.txt b/CMakeLists.txt
index 8bff344..fe44cd2 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -199,7 +199,7 @@ endif()
 # OpenCV cmake options
 # ----------------------------------------------------------------------------
 
-# ESP32 target option
+# ESP32 target option. Enable it with -DESP32=ON will disable/modify parts of the code for compilation to work
 OCV_OPTION(ESP32 "Compilation for esp32 target" OFF)
 
 OCV_OPTION(OPENCV_ENABLE_NONFREE "Enable non-free algorithms" OFF)
@@ -491,6 +491,7 @@ OCV_OPTION(OPENCV_ENABLE_MEMALIGN     "Enable posix_memalign or memalign usage"
 OCV_OPTION(ENABLE_PYLINT              "Add target with Pylint checks"                            (BUILD_DOCS OR BUILD_EXAMPLES) IF (NOT CMAKE_CROSSCOMPILING AND NOT APPLE_FRAMEWORK) )
 OCV_OPTION(ENABLE_FLAKE8              "Add target with Python flake8 checker"                    (BUILD_DOCS OR BUILD_EXAMPLES) IF (NOT CMAKE_CROSSCOMPILING AND NOT APPLE_FRAMEWORK) )
 
+# Add preprocessor definition seen by the code sources
 if(ESP32)
   message(STATUS "Enabled ESP32 target specific build")
   add_definitions(-DESP32)
@@ -659,6 +660,7 @@ include(cmake/OpenCVModule.cmake)
 #  Detect endianness of build platform
 # ----------------------------------------------------------------------------
 
+# if not working while compiling for esp32, change the next line in 'if(IOS OR ESP32)'
 if(IOS)
   # test_big_endian needs try_compile, which doesn't work for iOS
   # http://public.kitware.com/Bug/view.php?id=12288
diff --git a/cmake/checks/atomic_check.cpp b/cmake/checks/atomic_check.cpp
index 3192fe3..b8ac3a2 100644
--- a/cmake/checks/atomic_check.cpp
+++ b/cmake/checks/atomic_check.cpp
@@ -2,7 +2,8 @@
 
 static int test()
 {
-    std::atomic<long> x;
+    // std::atomic<long long> x;
+    std::atomic<long> x;            // esp32 doesn't support hardware 64bit atomic. FIXME: add software support
     return x;
 }
 
diff --git a/cmake/platforms/OpenCV-Generic.cmake b/cmake/platforms/OpenCV-Generic.cmake
new file mode 100644
index 0000000..bf3a029
--- /dev/null
+++ b/cmake/platforms/OpenCV-Generic.cmake
@@ -0,0 +1 @@
+# nop
diff --git a/esp32/scripts/resources/alloc_fix.cpp b/esp32/scripts/resources/alloc_fix.cpp
index a7f82df..b44f863 100644
--- a/esp32/scripts/resources/alloc_fix.cpp
+++ b/esp32/scripts/resources/alloc_fix.cpp
@@ -6,6 +6,7 @@
 
 #include "ade/memory/alloc.hpp"
 
+// esp32 uses memalign from malloc.h
 #if defined(_WIN32) || defined(__ANDROID__) || defined(ANDROID) || defined(ESP32)
 #include <malloc.h>
 #else
diff --git a/modules/core/include/opencv2/core/utils/allocator_stats.impl.hpp b/modules/core/include/opencv2/core/utils/allocator_stats.impl.hpp
index e418d7c..0e5e924 100644
--- a/modules/core/include/opencv2/core/utils/allocator_stats.impl.hpp
+++ b/modules/core/include/opencv2/core/utils/allocator_stats.impl.hpp
@@ -21,7 +21,8 @@ class AllocatorStatistics : public AllocatorStatisticsInterface
 {
 protected:
 #ifdef CV_CXX11
-    std::atomic<long> curr, total, total_allocs, peak;      // ESP32 modification (from <long long> to <long>)
+    // std::atomic<long long> curr, total, total_allocs, peak; 
+    std::atomic<long> curr, total, total_allocs, peak;      // esp32 doesn't support hardware 64bit atomic. FIXME: add software support
 #else
     volatile long long curr, total, total_allocs, peak;  // overflow is possible, CV_XADD operates with 'int' only
 #endif
diff --git a/modules/core/src/parallel.cpp b/modules/core/src/parallel.cpp
index f7183a9..5bc1a2e 100644
--- a/modules/core/src/parallel.cpp
+++ b/modules/core/src/parallel.cpp
@@ -942,6 +942,7 @@ int cv::getNumberOfCPUs(void)
 
 #endif
 
+// esp32 doesn't support sysconf call. FIXME: add support
 #if !defined(_WIN32) && !defined(__APPLE__) && !defined(ESP32)
 
     static unsigned cpu_count_sysconf = (unsigned)sysconf( _SC_NPROCESSORS_ONLN );
diff --git a/modules/core/src/system.cpp b/modules/core/src/system.cpp
index 6a2e58b..6aa6594 100644
--- a/modules/core/src/system.cpp
+++ b/modules/core/src/system.cpp
@@ -1000,6 +1000,7 @@ String tempfile( const char* suffix )
         fname = fname + "__opencv_temp.XXXXXX";
     }
 
+    // FIXME: esp32 compilation only find mktemp and not mkstemp
     //const int fd = mkstemp((char*)fname.c_str());
     //if (fd == -1) return String();
 
diff --git a/modules/imgproc/src/color.simd_helpers.hpp b/modules/imgproc/src/color.simd_helpers.hpp
index 79eaebe..0821e0d 100644
--- a/modules/imgproc/src/color.simd_helpers.hpp
+++ b/modules/imgproc/src/color.simd_helpers.hpp
@@ -136,6 +136,7 @@ public:
     {
     }
 
+// Optimization doesn't works with xtensa cross-compiler
 #pragma GCC push_options
 #pragma GCC optimize ("-O0")
     virtual void operator()(const Range& range) const CV_OVERRIDE
diff --git a/modules/imgproc/src/histogram.cpp b/modules/imgproc/src/histogram.cpp
index 54100cb..2c474ba 100644
--- a/modules/imgproc/src/histogram.cpp
+++ b/modules/imgproc/src/histogram.cpp
@@ -1777,6 +1777,7 @@ calcSparseBackProj_8u( std::vector<uchar*>& _ptrs, const std::vector<int>& _delt
 
 }
 
+// Optimization doesn't works with xtensa cross-compiler
 #pragma GCC push_options
 #pragma GCC optimize ("-O0")
 void cv::calcBackProject( const Mat* images, int nimages, const int* channels,