Add documentatio to exceptions.

Jojo-1000 · Jan
1 parent 9c709358
Showing 5 changed files with 93 additions and 51 deletions
hueplusplus/BaseHttpHandler.cpp
hueplusplus/HueException.cpp
hueplusplus/include/HueException.h
hueplusplus/include/HueExceptionMacro.h
hueplusplus/include/Utils.h
@@ -4,17 +4,20 @@
     Copyright (C) 2020  Jan Rogall		- developer\n
     Copyright (C) 2020  Moritz Wirger	- developer\n
  
-    This program is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 3 of the License, or
+    This file is part of hueplusplus.
+
+    hueplusplus is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
     (at your option) any later version.
-    This program is distributed in the hope that it will be useful,
+
+    hueplusplus is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-    You should have received a copy of the GNU General Public License
-    along with this program; if not, write to the Free Software Foundation,
-    Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+    GNU Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public License
+    along with hueplusplus.  If not, see <http://www.gnu.org/licenses/>.
 **/
  
 #include "include/BaseHttpHandler.h"
@@ -4,23 +4,26 @@
     Copyright (C) 2020  Jan Rogall		- developer\n
     Copyright (C) 2020  Moritz Wirger	- developer\n
  
-    This program is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 3 of the License, or
+    This file is part of hueplusplus.
+
+    hueplusplus is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
     (at your option) any later version.
-    This program is distributed in the hope that it will be useful,
+
+    hueplusplus is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-    You should have received a copy of the GNU General Public License
-    along with this program; if not, write to the Free Software Foundation,
-    Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+    GNU Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public License
+    along with hueplusplus.  If not, see <http://www.gnu.org/licenses/>.
 **/
  
 #include "include/HueException.h"
  
 HueException::HueException(FileInfo fileInfo, const std::string& message)
-    : HueException("Hue exception", std::move(fileInfo), message)
+    : HueException("HueException", std::move(fileInfo), message)
 {}
  
 const char* HueException::what() const noexcept
@@ -37,7 +40,7 @@ HueException::HueException(const char* exceptionName, FileInfo fileInfo, const s
     : fileInfo(std::move(fileInfo))
 {
     whatMessage = exceptionName;
-    whatMessage.append(" from");
+    whatMessage.append(" from ");
     whatMessage.append(this->fileInfo.ToString());
     whatMessage.append(" ");
     whatMessage.append(message);
@@ -45,7 +48,7 @@ HueException::HueException(const char* exceptionName, FileInfo fileInfo, const s
  
 HueAPIResponseException::HueAPIResponseException(
     FileInfo fileInfo, int error, std::string address, std::string description)
-    : HueException("Hue api response exception", std::move(fileInfo), GetMessage(error, address, description)),
+    : HueException("HueApiResponseException", std::move(fileInfo), GetMessage(error, address, description)),
       error(error),
       address(std::move(address)),
       description(std::move(description))
@@ -4,17 +4,20 @@
     Copyright (C) 2020  Jan Rogall		- developer\n
     Copyright (C) 2020  Moritz Wirger	- developer\n
  
-    This program is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 3 of the License, or
+    This file is part of hueplusplus.
+
+    hueplusplus is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
     (at your option) any later version.
-    This program is distributed in the hope that it will be useful,
+
+    hueplusplus is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-    You should have received a copy of the GNU General Public License
-    along with this program; if not, write to the Free Software Foundation,
-    Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+    GNU Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public License
+    along with hueplusplus.  If not, see <http://www.gnu.org/licenses/>.
 **/
  
 #ifndef _HUE_EXCEPTION_H
@@ -26,19 +29,30 @@
 //! \brief Contains information about error location, use CURRENT_FILE_INFO to create
 struct FileInfo
 {
+    //! \brief Current file name from __FILE__. Empty if unknown
     std::string filename;
+    //! \brief Current line number from __LINE__. -1 if unknown
     int line = -1;
+    //! \brief Current function from __func__. Empty if unknown
     std::string func;
  
+    //! \brief String representation of func, file and line.
+    //! \returns "<func> in <filename>:<line>" or "Unknown file" if unknown.
     std::string ToString() const;
 };
  
+//! \brief Exception class with file information. Base class of all custom exception classes
 class HueException : public std::exception
 {
 public:
-    //! \brief Creates HueException with information about the thrown location
+    //! \brief Creates HueException with information about the error and source
+    //! \param fileInfo Source of the error. Must not always be the throw location,
+    //! can also be a calling function which matches the cause better.
+    //! \param message Human readable error message.
     HueException(FileInfo fileInfo, const std::string& message);
  
+    //! \brief What message of the exception
+    //! \returns exception name, file info and constructor message as char* into member string
     const char* what() const noexcept override;
  
     //! \brief Filename and line where the exception was thrown or caused by
@@ -48,6 +62,10 @@ protected:
     //! \brief Creates HueException with child class name
     //!
     //! Should be used by subclasses which can append additional information to the end of whatMessage.
+    //! \param exceptionName class name of the subclass
+    //! \param fileInfo Source of the error. Must not always be the throw location,
+    //! can also be a calling function which matches the cause better.
+    //! \param message Human readable error message
     HueException(const char* exceptionName, FileInfo fileInfo, const std::string& message);
  
 private:
@@ -55,16 +73,31 @@ private:
     FileInfo fileInfo;
 };
  
+//! \brief Exception caused by a Hue API "error" response with additional information
+//!
+//! Refer to Hue developer documentation for more detail on specific error codes.
 class HueAPIResponseException : public HueException
 {
 public:
+    //! \brief Create exception with info from Hue API error
+    //! \param fileInfo Source of the error. Must not always be the throw location,
+    //! can also be a calling function which matches the cause better.
+    //! \param error Hue API error code from error response.
+    //! \param address URI the API call referred to from error response.
+    //! \param description Error description from response.
     HueAPIResponseException(FileInfo fileInfo, int error, std::string address, std::string description);
  
+    //! \brief Error number from Hue API error response.
+    //!
+    //! Refer to Hue developer documentation for meaning of error codes.
     int GetErrorNumber() const noexcept;
+    //! \brief Address the API call tried to access.
     const std::string& GetAddress() const noexcept;
+    //! \brief Error description
     const std::string& GetDescription() const noexcept;
  
 private:
+    //! \brief Creates exception message containing the given information
     static std::string GetMessage(int error, const std::string& addr, const std::string& description);
  
 private:
@@ -4,20 +4,20 @@
     Copyright (C) 2020  Jan Rogall		- developer\n
     Copyright (C) 2020  Moritz Wirger	- developer\n
  
-    This program is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 3 of the License, or
+    This file is part of hueplusplus.
+
+    hueplusplus is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
     (at your option) any later version.
-    This program is distributed in the hope that it will be useful,
+
+    hueplusplus is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-    You should have received a copy of the GNU General Public License
-    along with this program; if not, write to the Free Software Foundation,
-    Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+    GNU Lesser General Public License for more details.
  
-    This file contains a macro definition for getting the current line number.
-    It should only be included in cpp files and not in headers!
+    You should have received a copy of the GNU Lesser General Public License
+    along with hueplusplus.  If not, see <http://www.gnu.org/licenses/>.
 **/
  
 #include "HueException.h"
@@ -4,17 +4,20 @@
     Copyright (C) 2020  Jan Rogall		- developer\n
     Copyright (C) 2020  Moritz Wirger	- developer\n
  
-    This program is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 3 of the License, or
+    This file is part of hueplusplus.
+
+    hueplusplus is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
     (at your option) any later version.
-    This program is distributed in the hope that it will be useful,
+
+    hueplusplus is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-    You should have received a copy of the GNU General Public License
-    along with this program; if not, write to the Free Software Foundation,
-    Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+    GNU Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public License
+    along with hueplusplus.  If not, see <http://www.gnu.org/licenses/>.
 **/
  
 #ifndef _UTILS_H