docs: improvements to source code documentation (#1236)

src/platform/common.h

@@ -1,9 +1,4 @@
-//
-// Created by loki on 6/21/19.
-//
-
-#ifndef SUNSHINE_COMMON_H
-#define SUNSHINE_COMMON_H
+#pragma once
 
 #include <bitset>
 #include <filesystem>
@@ -215,8 +210,8 @@ namespace platf {
     }
 
     /**
-   * implementations must take ownership of 'frame'
-   */
+     * implementations must take ownership of 'frame'
+     */
     virtual int
     set_frame(AVFrame *frame, AVBufferRef *hw_frames_ctx) {
       BOOST_LOG(error) << "Illegal call to hwdevice_t::set_frame(). Did you forget to override it?";
@@ -227,14 +222,14 @@ namespace platf {
     set_colorspace(std::uint32_t colorspace, std::uint32_t color_range) {};
 
     /**
-   * Implementations may set parameters during initialization of the hwframes context
-   */
+     * Implementations may set parameters during initialization of the hwframes context
+     */
     virtual void
     init_hwframes(AVHWFramesContext *frames) {};
 
     /**
-   * Implementations may make modifications required before context derivation
-   */
+     * Implementations may make modifications required before context derivation
+     */
     virtual int
     prepare_to_derive_context(int hw_device_type) {
       return 0;
@@ -254,44 +249,44 @@ namespace platf {
   class display_t {
   public:
     /**
-   * When display has a new image ready or a timeout occurs, this callback will be called with the image.
-   * If a frame was captured, frame_captured will be true. If a timeout occurred, it will be false.
-   * 
-   * On Break Request -->
-   *    Returns false
-   * 
-   * On Success -->
-   *    Returns true
-   */
+     * When display has a new image ready or a timeout occurs, this callback will be called with the image.
+     * If a frame was captured, frame_captured will be true. If a timeout occurred, it will be false.
+     *
+     * On Break Request -->
+     *    Returns false
+     *
+     * On Success -->
+     *    Returns true
+     */
     using push_captured_image_cb_t = std::function<bool(std::shared_ptr<img_t> &&img, bool frame_captured)>;
 
     /**
-   * Use to get free image from the pool. Calls must be synchronized.
-   * Blocks until there is free image in the pool or capture is interrupted.
-   *
-   * Returns:
-   *     'true' on success, img_out contains free image
-   *     'false' when capture has been interrupted, img_out contains nullptr
-   */
+     * Use to get free image from the pool. Calls must be synchronized.
+     * Blocks until there is free image in the pool or capture is interrupted.
+     *
+     * Returns:
+     *     'true' on success, img_out contains free image
+     *     'false' when capture has been interrupted, img_out contains nullptr
+     */
     using pull_free_image_cb_t = std::function<bool(std::shared_ptr<img_t> &img_out)>;
 
     display_t() noexcept:
         offset_x { 0 }, offset_y { 0 } {}
 
     /**
-   * push_captured_image_cb --> The callback that is called with captured image,
-   *                            must be called from the same thread as capture()
-   * pull_free_image_cb --> Capture backends call this callback to get empty image
-   *                        from the pool. If backend uses multiple threads, calls to this
-   *                        callback must be synchronized. Calls to this callback and
-   *                        push_captured_image_cb must be synchronized as well.
-   * bool *cursor --> A pointer to the flag that indicates wether the cursor should be captured as well
-   * 
-   * Returns either:
-   *    capture_e::ok when stopping
-   *    capture_e::error on error
-   *    capture_e::reinit when need of reinitialization
-   */
+     * push_captured_image_cb --> The callback that is called with captured image,
+     *                            must be called from the same thread as capture()
+     * pull_free_image_cb --> Capture backends call this callback to get empty image
+     *                        from the pool. If backend uses multiple threads, calls to this
+     *                        callback must be synchronized. Calls to this callback and
+     *                        push_captured_image_cb must be synchronized as well.
+     * bool *cursor --> A pointer to the flag that indicates wether the cursor should be captured as well
+     *
+     * Returns either:
+     *    capture_e::ok when stopping
+     *    capture_e::error on error
+     *    capture_e::reinit when need of reinitialization
+     */
     virtual capture_e
     capture(const push_captured_image_cb_t &push_captured_image_cb, const pull_free_image_cb_t &pull_free_image_cb, bool *cursor) = 0;
 
@@ -368,14 +363,14 @@ namespace platf {
   audio_control();
 
   /**
- * display_name --> The name of the monitor that SHOULD be displayed
- *    If display_name is empty --> Use the first monitor that's compatible you can find
- *    If you require to use this parameter in a seperate thread --> make a copy of it.
- * 
- * config --> Stream configuration
- * 
- * Returns display_t based on hwdevice_type
- */
+   * display_name --> The name of the monitor that SHOULD be displayed
+   *    If display_name is empty --> Use the first monitor that's compatible you can find
+   *    If you require to use this parameter in a seperate thread --> make a copy of it.
+   *
+   * config --> Stream configuration
+   *
+   * Returns display_t based on hwdevice_type
+   */
   std::shared_ptr<display_t>
   display(mem_type_e hwdevice_type, const std::string &display_name, const video::config_t &config);
 
@@ -468,5 +463,3 @@ namespace platf {
   std::vector<std::string_view> &
   supported_gamepads();
 }  // namespace platf
-
-#endif  //SUNSHINE_COMMON_H