Improve Doxygen comments

.travis/dependencies.sh

@@ -4,6 +4,7 @@ if [[ $TRAVIS_OS_NAME == 'osx' ]]; then
   # Install dependencies for macOS
   brew update
   brew install libxml2
+  brew link -f libxml2
 
   # Get LLVM 3.9.0
   wget http://llvm.org/releases/3.9.0/clang+llvm-3.9.0-x86_64-apple-darwin.tar.xz

lib/include/ebc/BinaryMetadata.h

@@ -4,6 +4,8 @@
 #include <string>
 
 namespace ebc {
+
+/// Abstraction of the meta data linked to a binary object or archive.
 class BinaryMetadata {
  public:
   std::string GetFileFormatName() const;

lib/include/ebc/BitcodeArchive.h

@@ -9,29 +9,48 @@
 #include <vector>
 
 namespace ebc {
+
 class BitcodeFile;
 class BitcodeMetadata;
+
+/// A bitcode archive is a special kind of bitcode container created by Apple's
+/// version of LLVM. It contains a XAR archive with the (unlinked) bitcode
+/// files. Additional metadata is part of the archive's table of content.
 class BitcodeArchive : public BitcodeContainer {
  public:
   BitcodeArchive(const char* data, std::uint32_t size);
 
   BitcodeArchive(BitcodeArchive&& bitcodeArchive) noexcept;
 
+  /// Indicates whether the given bitcode container is a bitcode archive.
+  ///
+  /// @return True.
   virtual bool IsArchive() const override;
 
   /// Write container data to file. If no file name is provided, the file
   /// format name of the binary will be used, followed by the xar extension.
   /// This works even when compiled without xar support.
+  ///
+  /// @param fileName Optional file name for the XAR archive.
+  ///
+  /// @return The path to the XAR archive file.
   std::string WriteXarToFile(std::string fileName = "") const;
 
   /// Return the MetaData contained in this bitcode archive. This operation is
   /// cheap as the heavy lifting occurs at construction time. Metadata is empty
   /// if not compiled with xar support.
+  ///
+  /// @return The meta data.
   const BitcodeMetadata& GetMetadata() const;
 
   /// Extract individual bitcode files from this archive and return a vector of
   /// file names. This operation can be expensive as it decompresses each
   /// bitcode file. The result is empty if not compiled with xar support.
+  ///
+  /// @param extract Optional paramter indicating whether different bitcode
+  ///                files should be extracted and written to file.
+  ///
+  /// @return A vector of bitcode files.
   std::vector<BitcodeFile> GetBitcodeFiles(bool extract = false) const override;
 
  private:

lib/include/ebc/BitcodeContainer.h

@@ -18,18 +18,39 @@ class BitcodeContainer {
 
   virtual ~BitcodeContainer();
 
+  /// Indicates whether the given bitcode container is a bitcode archive.
+  ///
+  /// @return False.
   virtual bool IsArchive() const;
 
-  /// Returns the commands associated with the embedded bitcode.
+  /// Get the commands passed to the compiler front end.
+  ///
+  /// @return The commands passed to the compiler front end.
   const std::vector<std::string>& GetCommands() const;
+
+  /// Set the commands passed to the compiler front end.
+  ///
+  /// @param cmd The commands passed to the compiler front end.
   void SetCommands(const std::vector<std::string>& cmd);
 
+  /// Get the binary meta data associated with this bitcode container.
+  ///
+  /// @return The binary meta data.
   BinaryMetadata& GetBinaryMetadata();
+
+  /// Set the binary meta data associated with this bitcode container.
+  ///
+  /// @return  The binary meta data.
   const BinaryMetadata& GetBinaryMetadata() const;
 
-  /// Extract individual bitcode files from this container and return a vector of
-  /// file names. This operation can be expensive as it decompresses each
+  /// Extract individual bitcode files from this container and return a vector
+  /// of file names. This operation can be expensive as it decompresses each
   /// bitcode file.
+  ///
+  /// @param extract Optional paramter indicating whether different bitcode
+  ///                files should be extracted and written to file.
+  ///
+  /// @return A vector of bitcode files.
   virtual std::vector<BitcodeFile> GetBitcodeFiles(bool extract = false) const;
 
  protected:

lib/include/ebc/BitcodeFile.h

@@ -11,10 +11,17 @@ class BitcodeFile {
   std::string GetName() const;
 
   /// Get all commands passed to the compiler to create this bitcode file.
+  ///
+  /// @return A vector of strings with the clang front-end commands.
   const std::vector<std::string>& GetCommands() const;
+
+  /// Set all commands passed to the compiler to create this bitcode file.
+  ///
+  /// @param clangCommands A vector of strings with the clang front-end
+  ///                      commands.
   void SetCommands(const std::vector<std::string>& clangCommands);
 
-  /// Remove the actual bitcode file from the filesystem.
+  /// Remove the actual bitcode file from the file system.
   void Remove();
 
  private:

lib/include/ebc/BitcodeMetadata.h

@@ -8,26 +8,44 @@ struct _xmlDoc;
 struct _xmlNode;
 
 namespace ebc {
+
+/// Abstraction of bitcode meta data associated with a BitcodeArchive. The data
+/// comes from the table of content of the embedded XAR archive.
 class BitcodeMetadata {
  public:
   BitcodeMetadata(std::string xml);
   BitcodeMetadata(const BitcodeMetadata& bitcodeTOC) = delete;
 
   ~BitcodeMetadata();
 
-  /// Returns the metadata XML.
+  /// Returns the meta data as XML string.
+  ///
+  /// @return The XML data as a string.
   const std::string& GetXml() const;
 
   /// Get dynamic libraries used for linking.
+  ///
+  /// @return A vector of strings with the name of the dylibs this binary was
+  ///         linked against.
   std::vector<std::string> GetDylibs() const;
 
   /// Get options passed to linker.
+  ///
+  /// @return A list of strings with the options passed to the linker.
   std::vector<std::string> GetLinkOptions() const;
 
   /// Get the commands passed to clang for the given file.
+  ///
+  /// @param fileName The input file passed to the clang compiler.
+  ///
+  /// @return The comands passed to the clang front end for the given file.
   std::vector<std::string> GetClangCommands(std::string fileName) const;
 
   /// Get the commands passed to swiftc for the given file.
+  ///
+  /// @param fileName The input file passed to the swift compiler.
+  ///
+  /// @return The comands passed to the swift front end for the given file.
   std::vector<std::string> GetSwiftCommands(std::string fileName) const;
 
  private:

lib/include/ebc/BitcodeRetriever.h

@@ -16,23 +16,82 @@ class SectionRef;
 
 namespace ebc {
 class BitcodeContainer;
+
+/// Retrieves bitcode form an object file.
 class BitcodeRetriever {
  public:
+  /// Creates an instance of the bitcode retriever for the given object file.
+  ///
+  /// @param objectPath The file from which to retrieve bitcode.
   BitcodeRetriever(std::string objectPath);
+
+  /// Set the architecture for which to retrieve bitcode. This is relevant to
+  /// 'fat' object files containing multiple architectures. If no architecture
+  /// is set, bitcode is retrieved for all present architectures.
+  ///
+  /// @param arch The architecture.
   void SetArch(std::string arch);
 
+  /// Perform the actual bitcode retrieval. Depending on the type of the object
+  /// file the resulting list contains plain bitcode containers or bitcode
+  /// archives.
+  ///
+  /// @return A list of bitcode containers.
   std::vector<std::unique_ptr<BitcodeContainer>> GetBitcodeContainers();
 
  private:
+  /// Helper method for determining whether the given architecture should be
+  /// handled.
+  ///
+  /// @param arch The architecture.
+  ///
+  /// @return True if the architecture matches the set architure or when no
+  /// architecture is set. False otherwise.
   bool processArch(std::string arch) const;
 
+  /// Obtains all bitcode from an object. The method basically determines the
+  /// kind of object and dispatches the actual work to the specialized method.
+  ///
+  /// @param binary The binary object.
+  ///
+  /// @return A list of bitcode containers.
   std::vector<std::unique_ptr<BitcodeContainer>> GetBitcodeContainers(const llvm::object::Binary& binary) const;
+
+  /// Obtains all bitcode from an object archive.
+  ///
+  /// @param archive The object archive.
+  ///
+  /// @return A list of bitcode containers.
   std::vector<std::unique_ptr<BitcodeContainer>> GetBitcodeContainersFromArchive(
       const llvm::object::Archive& archive) const;
+
+  /// Reads bitcode from a Mach O object file.
+  ///
+  /// @param objectFile The Mach O object file.
+  ///
+  /// @return The bitcode container.
   std::unique_ptr<BitcodeContainer> GetBitcodeContainerFromMachO(const llvm::object::MachOObjectFile* objectFile) const;
+
+  /// Reads bitcode from a plain object file.
+  ///
+  /// @param objectFile The Mach O object file.
+  ///
+  /// @return The bitcode container.
   std::unique_ptr<BitcodeContainer> GetBitcodeContainerFromObject(const llvm::object::ObjectFile* objectFile) const;
 
+  /// Obtains data from a section.
+  ///
+  /// @param section The section from which the data should be obtained.
+  ///
+  /// @return A pair with the data and the size of the data.
   static std::pair<const char*, std::uint32_t> GetSectionData(const llvm::object::SectionRef& section);
+
+  /// Obtains compiler commands from a section. It automatically parses the
+  /// data into a vector.
+  ///
+  /// @param section The sectio from which to read the compiler commands.
+  ///
+  /// @return A vector of compiler commands.
   static std::vector<std::string> GetCommands(const llvm::object::SectionRef& section);
 
   std::string _objectPath;

lib/include/ebc/EbcError.h

@@ -4,6 +4,7 @@
 
 namespace ebc {
 
+/// Exception thrown by LibEBC.
 class EbcError : public std::runtime_error {
  public:
   using std::runtime_error::runtime_error;

lib/include/ebc/util/Bitcode.h

@@ -7,13 +7,24 @@ namespace ebc {
 namespace util {
 namespace bitcode {
 
-/// Returns true if the first four bytes of the given data match the LLVM bitcode magic number.
+/// Returns true if the first four bytes of the given data match the LLVM
+/// bitcode magic number.
+///
+/// @param data Binary data representing a bitcode file.
+///
+/// @return True if the magic number B17C is found.
 bool IsBitcodeFile(const char *data);
 
 /// Write data to file with given file name.
+///
+/// @param data Bitcode binary data.
+/// @param size Bitcode binary data size.
+/// @param fileName The desired filename for the bitcode file.
 void WriteFile(const char *data, std::uint32_t size, std::string fileName);
 
 /// Returns true if LibEBC is compiled with xar support.
+///
+/// @return True if and only if XAR support is enabled.
 bool HasXar();
 }
 }

lib/include/ebc/util/Namer.h

@@ -5,18 +5,27 @@
 namespace ebc {
 namespace util {
 
-/// Static class for generating unique file names with a monotonically increasing number.
+/// Static class for generating unique file names with a monotonically
+/// increasing number.
 class Namer {
  public:
   Namer() = delete;
 
-  /// Get a new unique file name. The file name number increases by one after this call.
+  /// Get a new unique file name. The file name number increases by one after
+  /// this call.
+  ///
+  /// @return A guaranteed unique file name.
   static std::string GetFileName();
 
   /// Set a destination directory path.
+  ///
+  /// @param path Destination directory path.
   static void SetPath(std::string path);
 
-  /// Set a global file name prefix. All subsequent file names will start with this prefix.
+  /// Set a global file name prefix. All subsequent file names will start with
+  /// this prefix.
+  ///
+  /// @param prefix The desired file name prefix.
   static void SetPrefix(std::string prefix);
 
  private:

lib/include/ebc/util/Xml.h

@@ -11,15 +11,43 @@ namespace util {
 namespace xml {
 
 /// Get the content of an XML node as string.
+///
+/// @param node The XML node.
+///
+/// @return The content of the given node.
 std::string GetContent(_xmlNode* node);
 
-/// Finds the first node at the same level or under the given root that has the given name.
+/// Finds the first node at the same level or under the given root that has the
+/// given name.
+///
+/// @param root The node where the search starts. Nodes at the same level of
+///             the root are considered.
+/// @param name The name of the desired node.
+///
+/// @return The first XML node encountered with the given name. Nullptr if none
+///         is found.
 _xmlNode* FindNodeWithName(_xmlNode* root, std::string name);
 
-/// Finds the first node at the same level or under the given root that has the given name and content.
+/// Finds the first node at the same level or under the given root that has the
+/// given name and content.
+///
+/// @param root The node where the search starts. Nodes on the same level are
+///             not considered.
+/// @param name The name of the desired node.
+/// @param content The content of the desired node.
+///
+/// @return The first node matching the given criteria. Nullptr if none is
+///         found.
 _xmlNode* FindNodeWithNameAndContent(_xmlNode* root, std::string name, std::string content);
 
-/// Get the content of each node with the given name at the same level of the given root node.
+/// Get the content of each node with the given name at the same level of the
+/// given root node.
+///
+/// @param root The node where the search starts. Nodes on the same level are
+///             considered.
+/// @param name The name of the desired node.
+///
+/// @return The content of each node matching the criteria.
 std::vector<std::string> GetTextFromNodesWithName(_xmlNode* root, std::string name);
 
 class XmlInitialization {