[PATCH, applied] {ctf,btf}-reader: Document the namespace for nicer apidoc

[Dodji Seketeli <dodji@redhat.com>]

Hello,

The apidoc is not generating any documentation for the libabigail::btf
and libabigail::ctf namespaces.

It turns out I need to add some doxygen comment to the these namespaces
in the source code.  Fixed thus.

	* include/abg-btf-reader.h (namespace btf): Add doxygen comment.
	Just adding it to the *.cc won't cut it, I am not sure why.
	* include/abg-ctf-reader.h (namespace ctf): Likewise.
	* src/abg-btf-reader.cc (namespace btf): Add doxygen comment.
	* src/abg-ctf-reader.cc (namespace ctf): Add doxygen commit.
	(create_reader, reset_reader): Fix doxygen comments.

Signed-off-by: Dodji Seketeli <dodji@redhat.com>
Applied to the master branch.
---
 include/abg-btf-reader.h | 45 ++++++++++++++++++++++++++++++++++------
 include/abg-ctf-reader.h |  2 ++
 src/abg-btf-reader.cc    |  1 +
 src/abg-ctf-reader.cc    | 18 +++++++---------
 4 files changed, 49 insertions(+), 17 deletions(-)

diff --git a/include/abg-btf-reader.h b/include/abg-btf-reader.h
index 9239d4f2..e891f268 100644
--- a/include/abg-btf-reader.h
+++ b/include/abg-btf-reader.h
@@ -18,15 +18,48 @@
 namespace abigail
 {
 
+/// Namespace of the reader for the BTF debug information.
 namespace btf
 {
 
-elf_based_reader_sptr
-create_reader(const std::string& elf_path,
-	      const vector<char**>& debug_info_root_paths,
-	      environment& env,
-	      bool load_all_types = false,
-	      bool linux_kernel_mode = false);
+  /// Create and return a BTF reader (or front-end) which is an instance
+  /// of @ref btf::reader.
+  ///
+  /// @param elf_path the path to the path to the elf file the reader is
+  /// to be used for.
+  ///
+  /// @param debug_info_root_paths a vector to the paths to the
+  /// directories under which the debug info is to be found for @p
+  /// elf_path.  Pass an empty vector if th debug info is not in a split
+  /// file.
+  ///
+  /// @param environment the environment used by the current context.
+  /// This environment contains resources needed by the BTF reader and
+  /// by the types and declarations that are to be created later.  Note
+  /// that ABI artifacts that are to be compared all need to be created
+  /// within the same environment.
+  ///
+  /// Please also note that the life time of this environment object
+  /// must be greater than the life time of the resulting @ref
+  /// reader the context uses resources that are allocated in the
+  /// environment.
+  ///
+  /// @param load_all_types if set to false only the types that are
+  /// reachable from publicly exported declarations (of functions and
+  /// variables) are read.  If set to true then all types found in the
+  /// debug information are loaded.
+  ///
+  /// @param linux_kernel_mode if set to true, then consider the special
+  /// linux kernel symbol tables when determining if a symbol is
+  /// exported or not.
+  ///
+  /// @return a smart pointer to the resulting btf::reader.
+  elf_based_reader_sptr
+  create_reader(const std::string& elf_path,
+		const vector<char**>& debug_info_root_paths,
+		environment& env,
+		bool load_all_types = false,
+		bool linux_kernel_mode = false);
 
 }//end namespace btf
 }//end namespace abigail
diff --git a/include/abg-ctf-reader.h b/include/abg-ctf-reader.h
index 58d1bc77..cd9e2dfe 100644
--- a/include/abg-ctf-reader.h
+++ b/include/abg-ctf-reader.h
@@ -23,6 +23,8 @@
 
 namespace abigail
 {
+
+/// Namespace of the reader for the CTF debug information.
 namespace ctf
 {
 
diff --git a/src/abg-btf-reader.cc b/src/abg-btf-reader.cc
index 25fcb685..ac47c2ad 100644
--- a/src/abg-btf-reader.cc
+++ b/src/abg-btf-reader.cc
@@ -35,6 +35,7 @@ namespace abigail
 {
 using namespace ir;
 
+/// Namespace of the reader for the BTF debug information.
 namespace btf
 {
 
diff --git a/src/abg-ctf-reader.cc b/src/abg-ctf-reader.cc
index cc3d2694..a377423a 100644
--- a/src/abg-ctf-reader.cc
+++ b/src/abg-ctf-reader.cc
@@ -42,6 +42,7 @@ ABG_END_EXPORT_DECLARATIONS
 
 namespace abigail
 {
+/// Namespace of the reader for the CTF debug information
 namespace ctf
 {
 using std::dynamic_pointer_cast;
@@ -1671,8 +1672,11 @@ fill_ctf_section(const Elf_Scn *elf_section, ctf_sect_t *ctf_section)
 /// from a given ELF file.
 ///
 /// @param elf_path the patch of some ELF file.
+///
+/// @param debug_info_root_paths the paths to where to find the debug
+/// info.
+///
 /// @param env a libabigail IR environment.
-
 elf_based_reader_sptr
 create_reader(const std::string& elf_path,
 	      const vector<char**>& debug_info_root_paths,
@@ -1692,16 +1696,8 @@ create_reader(const std::string& elf_path,
 /// @param elf_path the path to the elf file the context is to be used
 /// for.
 ///
-/// @param environment the environment used by the current context.
-/// This environment contains resources needed by the reader and by
-/// the types and declarations that are to be created later.  Note
-/// that ABI artifacts that are to be compared all need to be created
-/// within the same environment.
-///
-/// Please also note that the life time of this environment object
-/// must be greater than the life time of the resulting @ref
-/// reader the context uses resources that are allocated in the
-/// environment.
+/// @param debug_info_root_paths the paths pointing to where to find
+/// the debug info.
 void
 reset_reader(elf_based_reader&		rdr,
 	     const std::string&	elf_path,
-- 
2.39.3


-- 
		Dodji