Document some app.h/fuji.h functions

lib/app.h

@@ -1,35 +1,44 @@
 #ifndef APP_H
 #define APP_H
 
-/// Send current camera name to UI
+/// @brief Send current camera name to UI
 void app_send_cam_name(const char *name);
 
-/// OS level debug log
+/// @brief OS level debug log
 void plat_dbg(char *fmt, ...);
 
-/// printf to UI
+/// @brief Ping UI with update
 void app_print(char *fmt, ...);
+/// @brief Ping UI with update (accepts localized resource string)
+void app_print_id(int resid);
 
 // Test suite verbose logging
 void tester_log(char *fmt, ...);
 void tester_fail(char *fmt, ...);
 
-/// Bind to default or user-selected wifi device
+/// @brief Bind to default or user-selected wifi device
 int app_bind_socket_wifi(int sockfd);
 
-/// Eventually this will be removed when more than one connection is allowed at once
+/// @brief Get default PTP object
+/// @note Eventually this will be removed when more than one connection is allowed at once
 struct PtpRuntime *ptp_get(void);
 
-/// Call for every chunk/packet read
+/// @brief Called for every chunk/packet read
 void app_increment_progress_bar(int read);
 
-void app_print_id(int resid);
+/// @brief Get string ID from key/ID
 int app_get_string(const char *key);
+
+/// @brief Get download path for a file, for fopen()
 void app_get_file_path(char buffer[256], const char *filename);
 
+/// @brief Check if the current downloader thread has been marked as canceled
 int app_check_thread_cancel(void);
 
+/// @brief Pings the frontned when a file is going to be downloaded
 void app_downloading_file(const struct PtpObjectInfo *oi);
+
+/// @brief Pings the frontend when a file has been downloaded
 void app_downloaded_file(const struct PtpObjectInfo *oi, const char *path);
 
 #endif

lib/fuji.h

@@ -17,7 +17,7 @@ enum DiscoverRet {
 	FUJI_D_GO_PTP = 2,
 	FUJI_D_CANCELED = 3,
 	FUJI_D_IO_ERR = 4,
-	/// In the case that Fuji's software prevents us from listening to the camera, let the user know to kill it
+	// TODO: In the case that Fuji's software prevents us from listening to the camera, let the user know to kill it
 	FUJI_D_OPEN_DENIED = 5,
 	FUJI_D_INVALID_NETWORK = 6,
 };
@@ -50,55 +50,75 @@ struct FujiDeviceKnowledge {
 };
 struct FujiDeviceKnowledge *fuji_get(struct PtpRuntime *r);
 
+/// @brief Do a weird hack where we GetPartialObject on the first few kb of a file, then grab the thumbnail
+/// from the exif data. Not reliable. TODO: Move to camlib.c
 int ptp_get_partial_exif(struct PtpRuntime *r, int handle, int *offset, int *length);
 
+/// @note Not a part of camlib
+void ptp_report_error(struct PtpRuntime *r, const char *reason, int code);
+
+/// @note This will block
 int fuji_discover_thread(struct DiscoverInfo *info, char *client_name, void *arg);
+/// @brief Callback for discovery. Called when a new device wanting to pair is discovered. Return 1 if connection accepted
+/// @note to be defined by frontend
 int fuji_discover_ask_connect(void *arg, struct DiscoverInfo *info);
+/// @brief Check if discovery is canceled
+/// @note to be defined by frontend
 int fuji_discovery_check_cancel(void *arg);
+/// @brief Update the frontend on UI discovery progress, 0-7
+/// @note to be defined by frontend
 void fuji_discovery_update_progress(void *arg, int progress);
 
-// (Not a part of camlib)
-void ptp_report_error(struct PtpRuntime *r, const char *reason, int code);
-
+/// @brief Initializes allocations for Fuji PTP session
 int fuji_reset_ptp(struct PtpRuntime *r);
 
+/// @brief Setup the event/liveview sockets for remote mode
 int fuji_setup_remote_mode(struct PtpRuntime *r);
 
+/// @brief Main entry function for PTP/IP
 int fuji_setup(struct PtpRuntime *r);
 
+/// @brief Import files, based on an array of object IDs. Object Info will be fetched for each, mask will dictate if it's skipped or not.
 int fuji_import_objects(struct PtpRuntime *r, int *object_ids, int length, int mask);
 
 // Test suite stuff
 int fuji_test_suite(struct PtpRuntime *r);
 int fuji_test_setup(struct PtpRuntime *r);
 int fuji_test_filesystem(struct PtpRuntime *r);
 
-// Send init packet, receive response
+/// @brief Standard REQ/ACK for PTP/IP connection
 int ptpip_fuji_init_req(struct PtpRuntime *r, char *device_name, struct PtpFujiInitResp *resp);
 
+/// @brief Configure some mandatory viewer/gallery related version properties
 int fuji_config_version(struct PtpRuntime *r);
+/// @brief Determine and set what ClientState we need to be in
 int fuji_config_init_mode(struct PtpRuntime *r);
 
+/// @brief Configure the camera for the image viewer/gallery
 int fuji_config_image_viewer(struct PtpRuntime *r);
+/// @brief Fetch and parse initial device info
 int fuji_config_device_info_routine(struct PtpRuntime *r);
 
 int fuji_remote_mode_open_sockets(struct PtpRuntime *r);
 int fuji_remote_mode_end(struct PtpRuntime *r);
 
+/// @brief Poll events for setup event. Returns immediately if access is already granted.
 int fuji_wait_for_access(struct PtpRuntime *r);
 
-// Receives events once, and updates info struct with changes
+/// @brief Receives events once, and updates info struct with changes
 int fuji_get_events(struct PtpRuntime *r);
 
 // Enable/disable compression prop for downloading photos
 int fuji_disable_compression(struct PtpRuntime *r);
 int fuji_enable_compression(struct PtpRuntime *r);
 
+/// @brief Covers classic 'SELECT_MULTIPLE' feature found in 2013-2017 cams.
 int fuji_download_classic(struct PtpRuntime *r);
 
 // Another socket on top of the 2 that camlib connects to
 int ptpip_connect_video(struct PtpRuntime *r, const char *addr, int port);
 
+/// Main entry function for all USB connections
 int fujiusb_setup(struct PtpRuntime *r);
 int fujitether_setup(struct PtpRuntime *r);
 
@@ -108,7 +128,8 @@ int fuji_register_device_info(struct PtpRuntime *r, uint8_t *data);
 int ptp_fuji_get_init_info(struct PtpRuntime *r, struct PtpFujiInitResp *resp);
 int ptp_fuji_parse_object_info(struct PtpRuntime *r, struct PtpFujiObjectInfo *oi);
 
-/// Download camera settings backup file
+/// @brief Download camera settings backup file
+/// @note USB only, in backup/raw conv mode.
 int fujiusb_download_backup(struct PtpRuntime *r, FILE *f);
 
 #define PTP_SELET_JPEG (1 << 0)