libragephoto: improve documentation

2024-04-09 05:21:36 +02:00 · 2024-04-09 05:21:36 +02:00 · bc9065e8dc
commit bc9065e8dc
parent 0fa69667d0
9 changed files with 234 additions and 109 deletions
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@ -1,6 +1,6 @@
 #[[**************************************************************************
 * libragephoto RAGE Photo Parser
-* Copyright (C) 2021 Syping
+* Copyright (C) 2021-2024 Syping
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
@ -24,12 +24,13 @@ if (NOT DOXYGEN_FOUND)
    message(FATAL_ERROR "Doxygen is needed to build the documentation.")
 endif()

-configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
+configure_file("${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in" "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile" @ONLY)
 add_custom_target(
    doc ALL
-    COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
-    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+    COMMAND "${DOXYGEN_EXECUTABLE}" "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile"
    COMMENT "Generate API documentation with Doxygen"
+    SOURCES "build.dox" "index.dox" "usage.dox"
+    WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
    VERBATIM
 )
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html DESTINATION ${CMAKE_INSTALL_DOCDIR})
+install(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html" DESTINATION "${CMAKE_INSTALL_DOCDIR}")
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@ -1,16 +1,18 @@
 PROJECT_NAME           = "libragephoto"
 PROJECT_NUMBER         = "Version: @ragephoto_VERSION@"
-INPUT                  = "@CMAKE_CURRENT_SOURCE_DIR@/index.doc" \
-                         "@CMAKE_CURRENT_SOURCE_DIR@/build.doc" \
-                         "@CMAKE_CURRENT_SOURCE_DIR@/usage.doc" \
-                         "src/core"
+INPUT                  = "src/core" \
+                         "@CMAKE_CURRENT_SOURCE_DIR@/index.dox" \
+                         "@CMAKE_CURRENT_SOURCE_DIR@/build.dox" \
+                         "@CMAKE_CURRENT_SOURCE_DIR@/usage.dox"
 OUTPUT_DIRECTORY       = "@CMAKE_CURRENT_BINARY_DIR@"
+FULL_PATH_NAMES        = NO
 EXTRACT_PRIVATE        = NO
 ENABLE_PREPROCESSING   = YES
 MACRO_EXPANSION        = YES
-EXPAND_ONLY_PREDEF     = YES
+EXPAND_ONLY_PREDEF     = NO
 PREDEFINED             = "__cplusplus=201703L" \
                         "RAGEPHOTO_CXX_STD=17" \
-                         "@LIBRAGEPHOTO_API@" \
                         "LIBRAGEPHOTO_C_PUBLIC=" \
-                         "LIBRAGEPHOTO_CXX_PUBLIC="
+                         "LIBRAGEPHOTO_CXX_PUBLIC=" \
+                         "INT32_C(val)=val" \
+                         "UINT32_C(val)=val##U"
--- a/doc/build.dox
+++ b/doc/build.dox
@ -21,6 +21,7 @@ To customise your libragephoto build, the following <a href="#flags">Optional CM
 -DRAGEPHOTO_BENCHMARK=ON
 -DRAGEPHOTO_C_API=OFF
 -DRAGEPHOTO_C_LIBRARY=ON
+-DRAGEPHOTO_DEBUG=ON
 -DRAGEPHOTO_DOC=ON
 -DRAGEPHOTO_EXAMPLE_GTKVIEWER=ON
 -DRAGEPHOTO_EXAMPLE_QTVIEWER=ON
--- a/doc/index.dox
+++ b/doc/index.dox
@ -9,12 +9,11 @@

 <b>Getting started</b>  
 \subpage Build "Build libragephoto"  
-\subpage Usage "Using libragephoto"
+\subpage Usage "Using libragephoto"  

 <b>Reference</b>  
-ragephoto::cxx_abi::photo (C++ API)  
-ragephoto::c_abi::photo (C++ API based on C API)  
-RagePhoto.h (C API)  
+\ref RagePhotoInstance "RagePhoto C API"  
+\ref ragephoto::photo "RagePhoto C++ API"  
 RagePhotoData (Data Object Struct)  
 RagePhotoFormatParser (Custom Format Parser Struct)

--- a/doc/usage.dox
+++ b/doc/usage.dox
@ -2,15 +2,13 @@

 <h3 id="api_cxx">C++ API</h3>

-<h4 id="cxx_include_usage">Including and using RagePhoto</h4>
-
-Include RagePhoto
+<h4 id="cxx_include">Including RagePhoto</h4>

 \code{.cpp}
 #include <RagePhoto>
 \endcode

-Create a RagePhoto object
+Initializing a RagePhoto object

 \code{.cpp}
 RagePhoto ragePhoto;
@ -21,16 +19,14 @@ RagePhoto ragePhoto;
 From a file using RagePhoto::loadFile

 \code{.cpp}
-const char* filename = "PGTA5123456789";
-const bool loaded = ragePhoto.loadFile(filename);
+const bool loaded = ragePhoto.loadFile("PGTA5123456789");
 \endcode

 From a file using RagePhoto::load(const std::string&)

 \code{.cpp}
 // Reading file
-const char* filename = "PGTA5123456789";
-std::ifstream ifs(filename, std::ios::in | std::ios::binary);
+std::ifstream ifs("PGTA5123456789", std::ios::in | std::ios::binary);
 if (!ifs.is_open())
    return;
 std::string sdata(std::istreambuf_iterator<char>{ifs}, {});
@ -46,7 +42,7 @@ From a char* using RagePhoto::load(const char*, size_t)
 const bool loaded = ragePhoto.load(data, size);
 \endcode

-<h4 id="cxx_using">Using a Photo</h4>
+<h4 id="cxx_using">Querying Photo data</h4>

 \code{.cpp}
 // Returns the Photo Format
@ -85,64 +81,21 @@ Saving the JPEG from a Photo

 \code{.cpp}
 // Example saveJpeg function
-bool saveJpeg(RagePhoto* ragePhoto, const std::string& filename) {
+bool saveJpeg(RagePhoto &ragePhoto, const std::string &filename) {
    std::ofstream ofs(filename, std::ios::out | std::ios::binary | std::ios::trunc);
    if (!ofs.is_open())
        return false;
-    ofs << ragePhoto->jpeg();
+    ofs << ragePhoto.jpeg();
    const bool saved = ofs.good();
    ofs.close();
    return saved;
 }

 // Using the saveJpeg function
-const char* filename = "PGTA5123456789.jpg";
-const bool saved = saveJpeg(&ragePhoto, filename);
+const bool saved = saveJpeg(ragePhoto, "photo.jpg");
 \endcode

-Using the JPEG in GTK+ (gtkmm)
-
-\code{.cpp}
-// Writing pixbuf loader
-GdkPixbufLoader* pixbuf_loader = gdk_pixbuf_loader_new();
-gdk_pixbuf_loader_write(pixbuf_loader, reinterpret_cast<const guchar*>(ragePhoto.jpegData()), ragePhoto.jpegSize(), nullptr);
-GdkPixbuf* pixbuf = gdk_pixbuf_loader_get_pixbuf(pixbuf_loader);
-gdk_pixbuf_loader_close(pixbuf_loader, nullptr);
-
-// Set image
-Gtk::Image image;
-image.set(Glib::wrap(pixbuf));
-\endcode
-
-Using the JPEG in Qt
-
-\code{.cpp}
-// Returns the JPEG as QImage
-const QImage image = QImage::fromData(QByteArray::fromRawData(ragePhoto.jpegData(), ragePhoto.jpegSize()), "JPEG");
-
-// Loading the JPEG in QImage
-QImage image;
-const bool loaded = image.loadFromData(QByteArray::fromRawData(ragePhoto.jpegData(), ragePhoto.jpegSize()), "JPEG");
-\endcode
-
-Using the JSON in Boost.JSON
-
-\code{.cpp}
-boost::json::error_code ec;
-const boost::json::value jv = boost::json::parse(ragePhoto.json(), ec);
-if (ec)
-    return;
-\endcode
-
-Using the JSON in Qt
-
-\code{.cpp}
-const QJsonDocument jd = QJsonDocument::fromJson(ragePhoto.json());
-if (jd.isNull())
-    return;
-\endcode
-
-<h4 id="cxx_error">Detect Photo errors</h4>
+<h4 id="cxx_error">Querying last error</h4>

 \code{.cpp}
 const int32_t error = ragePhoto.error();
@ -164,6 +117,110 @@ default:

 Available error codes: RagePhoto::Error

+<h3 id="api_c">C API</h3>
+
+<h4 id="c_include">Including RagePhoto</h4>
+
+\code{.c}
+#include <RagePhoto.h>
+\endcode
+
+Initializing a RagePhoto instance
+
+\code{.c}
+ragephoto_t instance = ragephoto_open();
+\endcode
+
+Destroying a RagePhoto instance
+
+\code{.c}
+ragephoto_close(instance);
+\endcode
+
+<h4 id="c_loading">Loading a Photo</h4>
+
+From a file using ragephoto_loadfile(ragephoto_t, const char*)
+
+\code{.c}
+const bool loaded = ragephoto_loadfile(instance, "PGTA5123456789");
+\endcode
+
+From a char* using ragephoto_load(ragephoto_t, const char*, size_t)
+
+\code{.c}
+const bool loaded = ragephoto_load(instance, data, size);
+\endcode
+
+<h4 id="c_using">Querying Photo data</h4>
+
+\code{.c}
+// Returns the Photo Format
+const uint32_t format = ragephoto_getphotoformat(instance);
+
+// Returns the JPEG as const char*
+const char* jpeg = ragephoto_getphotojpeg(instance);
+const uint32_t size = ragephoto_getphotosize(instance);
+
+// Returns the JSON
+const char* json = ragephoto_getphotojson(instance);
+
+// Returns the Title
+const char* title = ragephoto_getphototitle(instance);
+\endcode
+
+Detecting if Photo is from GTA V or RDR 2
+
+\code{.c}
+switch (ragephoto_getphotoformat(instance)) {
+case RAGEPHOTO_FORMAT_GTA5:
+    printf("GTA V format detected\n");
+    break;
+case RAGEPHOTO_FORMAT_RDR2:
+    printf("RDR 2 format detected\n");
+    break;
+default:
+    printf("Unknown format detected\n");
+}
+\endcode
+
+Saving the JPEG from a Photo
+
+\code{.c}
+// Example saveJpeg function
+bool saveJpeg(ragephoto_t instance, const char* filename) {
+    FILE* file = fopen(filename, "wb");
+    if (!file)
+        return false;
+    const uint32_t jpegSize = ragephoto_getphotosize(instance);
+    const size_t writeSize = fwrite(ragephoto_getphotojpeg(instance), sizeof(char), jpegSize, file);
+    fclose(file);
+    return (jpegSize == writeSize);
+}
+
+// Using the saveJpeg function
+const bool saved = saveJpeg(instance, "photo.jpg");
+\endcode
+
+<h4 id="c_error">Querying last error</h4>
+
+\code{.c}
+const int32_t error = ragephoto_error(instance);
+switch (error) {
+case RAGEPHOTO_ERROR_NOFORMATIDENTIFIER:
+    printf("No format identifier\n");
+    break;
+case RAGEPHOTO_ERROR_INCOMPATIBLEFORMAT:
+    printf("Incompatible format\n");
+    break;
+// Detect for more errors here...
+case RAGEPHOTO_ERROR_NOERROR:
+    printf("No error detected\n");
+    break;
+default:
+    printf("Unknown error detected\n");
+}
+\endcode
+
 <h3 id="cmake">Including libragephoto in a CMake project</h3>

 <h4 id="cmake_pkgconfig">Using PkgConfig</h4>