diff --git a/userspace/libsinsp/plugin.cpp b/userspace/libsinsp/plugin.cpp
index d008cbf140..63619fd785 100755
--- a/userspace/libsinsp/plugin.cpp
+++ b/userspace/libsinsp/plugin.cpp
@@ -158,13 +158,15 @@ bool sinsp_plugin::init(const std::string &config, std::string &errstr)
 	std::string conf = config;
 	validate_init_config(conf);
 
-	ss_plugin_init_input in;
-	ss_plugin_init_tables_input tables_in;
-	ss_plugin_table_fields_vtable_ext table_fields_ext;
+	ss_plugin_init_input in = {};
 	in.owner = this;
 	in.get_owner_last_error = sinsp_plugin::get_owner_last_error;
 	in.tables = NULL;
 	in.config = conf.c_str();
+
+	ss_plugin_init_tables_input tables_in = {};
+	ss_plugin_table_fields_vtable_ext table_fields_ext = {};
+
 	if (m_caps & (CAP_PARSING | CAP_EXTRACTION))
 	{
 		tables_in.fields_ext = &table_fields_ext;
@@ -193,11 +195,13 @@ bool sinsp_plugin::init(const std::string &config, std::string &errstr)
 	// resolve post-init event code filters
 	if (m_caps & CAP_EXTRACTION)
 	{
+		/* Here we populate the `m_extract_event_codes` for the plugin, while `m_extract_event_sources` is already populated in the plugin_init */
 		resolve_dylib_compatible_codes(m_handle->api.get_extract_event_types,
 			m_extract_event_sources, m_extract_event_codes);
 	}
 	if (m_caps & CAP_PARSING)
 	{
+		/* Here we populate the `m_parse_event_codes` for the plugin, while `m_parse_event_sources` is already populated in the plugin_init */
 		resolve_dylib_compatible_codes(m_handle->api.get_parse_event_types,
 			m_parse_event_sources, m_parse_event_codes);
 	}
@@ -389,8 +393,8 @@ void sinsp_plugin::resolve_dylib_compatible_sources(
 {
 	resolve_dylib_json_strlist(name(), symbol, get_sources, sources, true);
 
-	// A plugin with source capability must extract/parse events
-	// from its own specific source (if it has one)
+	// A plugin with source capability extracts/parses events
+	// from its own specific source (if no other sources are specified)
 	if (m_caps & CAP_SOURCING && !m_event_source.empty())
 	{
 		sources.insert(m_event_source);
@@ -450,6 +454,7 @@ bool sinsp_plugin::resolve_dylib_symbols(std::string &errstr)
 
 	if(m_caps & CAP_SOURCING)
 	{
+		/* Default case: no id and no source */
 		m_id = 0;
 		m_event_source.clear();
 		if (m_handle->api.get_id != NULL
@@ -568,6 +573,7 @@ bool sinsp_plugin::resolve_dylib_symbols(std::string &errstr)
 			m_fields.push_back(tf);
 		}
 
+		// This API is not compulsory for the extraction capability
 		resolve_dylib_compatible_sources("get_extract_event_sources",
 			m_handle->api.get_extract_event_sources, m_extract_event_sources);
 	}
diff --git a/userspace/libsinsp/plugin.h b/userspace/libsinsp/plugin.h
index 70d14bd540..b2639b3a4a 100755
--- a/userspace/libsinsp/plugin.h
+++ b/userspace/libsinsp/plugin.h
@@ -234,6 +234,7 @@ class sinsp_plugin
 	std::string m_event_source;
 
 private:
+	/* this checks if we already called the init API */
 	bool m_inited;
 	ss_plugin_t* m_state;
 	plugin_handle_t* m_handle;
@@ -256,6 +257,7 @@ class sinsp_plugin
 	std::shared_ptr<libsinsp::state::table_registry> m_table_registry;
 	std::vector<ss_plugin_table_info> m_table_infos;
 	std::unordered_map<std::string, owned_table_t> m_owned_tables;
+	/* contains tables that the plugin accessed at least once */
 	std::unordered_map<std::string, accessed_table_t> m_accessed_tables;
 
 	/** Async Events **/
diff --git a/userspace/libsinsp/plugin_filtercheck.cpp b/userspace/libsinsp/plugin_filtercheck.cpp
index 8a6330d7f7..5f925fffe1 100755
--- a/userspace/libsinsp/plugin_filtercheck.cpp
+++ b/userspace/libsinsp/plugin_filtercheck.cpp
@@ -150,7 +150,11 @@ bool sinsp_filter_check_plugin::extract(sinsp_evt *evt, OUT vector<extract_value
 	}
 
 	auto type = m_info.m_fields[m_field_id].m_type;
+
+	// here we want to extract just one field
 	uint32_t num_fields = 1;
+
+	// populate the field to extract for the plugin
 	ss_plugin_extract_field efield;
 	efield.field_id = m_field_id;
 	efield.field = m_info.m_fields[m_field_id].m_name;
diff --git a/userspace/libsinsp/plugin_filtercheck.h b/userspace/libsinsp/plugin_filtercheck.h
index 9817e053f1..ae4d761dee 100755
--- a/userspace/libsinsp/plugin_filtercheck.h
+++ b/userspace/libsinsp/plugin_filtercheck.h
@@ -57,6 +57,9 @@ class sinsp_filter_check_plugin : public sinsp_filter_check
 	char* m_arg_key;
 	uint64_t m_arg_index;
 	bool m_arg_present;
+
+	// This vector is an optimization to avoid a linear search
+	// in the plugin source set.
 	std::vector<bool> m_compatible_plugin_sources_bitmap;
 	std::shared_ptr<sinsp_plugin> m_eplugin;
 
@@ -69,4 +72,4 @@ class sinsp_filter_check_plugin : public sinsp_filter_check
 	// extract_arg_key() extracts a valid string from the argument. If we pass
 	// a numeric argument, it will be converted to string. 
 	void extract_arg_key();
-};
\ No newline at end of file
+};
diff --git a/userspace/libsinsp/plugin_table_api.cpp b/userspace/libsinsp/plugin_table_api.cpp
index a9841bf0b2..77c78e897c 100755
--- a/userspace/libsinsp/plugin_table_api.cpp
+++ b/userspace/libsinsp/plugin_table_api.cpp
@@ -1325,6 +1325,7 @@ void sinsp_plugin::table_field_api(ss_plugin_table_fields_vtable& out, ss_plugin
 	extout.list_table_fields = dispatch_list_fields;
 	extout.add_table_field = dispatch_add_field;
 	extout.get_table_field = dispatch_get_field;
+	/* Deprecated */
 	out.list_table_fields = extout.list_table_fields;
 	out.add_table_field = extout.add_table_field;
 	out.get_table_field = extout.get_table_field;
@@ -1338,6 +1339,7 @@ void sinsp_plugin::table_read_api(ss_plugin_table_reader_vtable& out, ss_plugin_
 	extout.read_entry_field = dispatch_read_entry_field;
 	extout.release_table_entry = dispatch_release_table_entry;
 	extout.iterate_entries = dispatch_iterate_entries;
+	/* Deprecated */
 	out.get_table_name = extout.get_table_name;
 	out.get_table_size = extout.get_table_size;
 	out.get_table_entry = extout.get_table_entry;
diff --git a/userspace/libsinsp/sinsp.cpp b/userspace/libsinsp/sinsp.cpp
index d75d5046e8..0716fedbac 100644
--- a/userspace/libsinsp/sinsp.cpp
+++ b/userspace/libsinsp/sinsp.cpp
@@ -2815,20 +2815,29 @@ void sinsp::handle_plugin_async_event(const sinsp_plugin& p, std::unique_ptr<sin
 	// in the event stream.
 	if (!is_capture())
 	{
-		// note: async events get assigned the same event source as the
-		// currently-open one. In case no plugin is open, we set it to zero
-		// to indicate the regular "syscall" source. Otherwise we set the ID
-		// to the one of the currently-open ID, which can potentially be zero
-		// too in case the plugin does not define any specific event source.
-		// However, we also need to check if the plugin's async capability
-		// is compatible with the currently-open event source, and reject
-		// the event if that's not the case.
+		// note: async events are injected in the same event source as the
+		// currently open one. (Right now we can have just one event source open
+		// per inspector). There are 2 cases:
+		//
+		// 1. If a source plugin is open the async events can only
+		//    be injected in the plugin source.
+		// 2. If no source plugins are loaded the async events can only
+		//    be injected in the syscall source.
+		//
+		// We need to check if the async plugin specified an event source
+		// compliant with the above rules, in the `get_async_event_sources` API.
+		// We reject the event if that's not the case.
 		//
 		// todo(jasondellaluce): here we are assuming that the "syscall" event
 		// source is always at index 0 in the inspector's event source list,
 		// change this code if this assumption ever stops being true.
+		
+		// default: syscall source
 		size_t cur_evtsrc_idx = 0;
 		uint32_t cur_plugin_id = 0;
+		
+		// If we have a source plugin, we search for its event source and we update the current event source.
+		// Otherwise the current event source remains the syscall one.
 		if (is_plugin())
 		{
 			cur_plugin_id = m_input_plugin->id();