Improve documentation

petabyt · Nov 29, 2024 · 3e2fb1a · 3e2fb1a
1 parent 1d40fd5
commit 3e2fb1a
Show file tree

Hide file tree

Showing 15 changed files with 303 additions and 90 deletions.
diff --git a/Doxyfile b/Doxyfile
@@ -1,4 +1,14 @@
 PROJECT_NAME           = "camlib"
 PROJECT_BRIEF          = "Documentation for camlib is still a work-in-progress"
-INPUT                  = README.md docs/chdk.md docs/ml.md docs/ptp.md src/camlib.h src/cl_ops.h
+INPUT                  = README.md docs/chdk.md docs/ml.md docs/ptp.md \
+rc/camlib.h  src/cl_backend.h  src/cl_bind.h  src/cl_data.h  src/cl_enum.h  src/cl_ops.h  src/ptp.h
 USE_MDFILE_AS_MAINPAGE = README.md
+GENERATE_LATEX         = NO
+GENERATE_HTML          = YES
+SOURCE_BROWSER = YES
+LAYOUT_FILE = docs/DoxygenLayout.xml
+
+VERBATIM_HEADERS       = NO
+
+EXAMPLE_PATH           = examples/usb.c
+EXAMPLE_PATTERNS       = *
diff --git a/Makefile b/Makefile
@@ -1,6 +1,6 @@
 -include config.mak
 
-CFLAGS := -Isrc/ -g -fpic -Wall -Wshadow -Wcast-qual -Wpedantic -Werror=incompatible-pointer-types -Werror=deprecated-declarations
+CFLAGS := -Isrc/ -g -fpic -Wall -Wshadow -Wcast-qual -Wpedantic -Werror=incompatible-pointer-types -Werror=deprecated-declarations -Wstrict-aliasing=3
 CFLAGS += -D CAMLIB_NO_COMPAT -D VERBOSE
 
 # Camlib needs to be compiled with these files, with some exceptions:

diff --git a/docs/DoxygenLayout.xml b/docs/DoxygenLayout.xml
@@ -0,0 +1,248 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<doxygenlayout version="1.0">
+  <!-- Generated by doxygen 1.9.8 -->
+  <!-- Navigation index tabs for HTML output -->
+  <navindex>
+    <tab type="mainpage" visible="yes" title=""/>
+    <tab type="topics" visible="yes" title="API" intro=""/>
+    <tab type="pages" visible="yes" title="Extras" intro=""/>
+    <tab type="modules" visible="yes" title="" intro="">
+      <tab type="modulelist" visible="yes" title="" intro=""/>
+      <tab type="modulemembers" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="namespaces" visible="yes" title="">
+      <tab type="namespacelist" visible="yes" title="" intro=""/>
+      <tab type="namespacemembers" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="concepts" visible="yes" title="">
+    </tab>
+    <tab type="interfaces" visible="yes" title="">
+      <tab type="interfacelist" visible="yes" title="" intro=""/>
+      <tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
+      <tab type="interfacehierarchy" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="user" url="md_docs_2ml.html" visible="yes" title="Licence"/>
+    <tab type="filelist" visible="yes" title="" intro=""/>
+    <tab type="examples" visible="yes" title="Examples" intro=""/>
+  </navindex>
+
+  <!-- Layout definition for a class page -->
+  <class>
+    <briefdescription visible="yes"/>
+    <includes visible="$SHOW_HEADERFILE"/>
+    <inheritancegraph visible="$CLASS_GRAPH"/>
+    <collaborationgraph visible="yes"/>
+    <memberdecl>
+      <nestedclasses visible="yes" title=""/>
+      <publictypes title=""/>
+      <services title=""/>
+      <interfaces title=""/>
+      <publicslots title=""/>
+      <signals title=""/>
+      <publicmethods title=""/>
+      <publicstaticmethods title=""/>
+      <publicattributes title=""/>
+      <publicstaticattributes title=""/>
+      <protectedtypes title=""/>
+      <protectedslots title=""/>
+      <protectedmethods title=""/>
+      <protectedstaticmethods title=""/>
+      <protectedattributes title=""/>
+      <protectedstaticattributes title=""/>
+      <packagetypes title=""/>
+      <packagemethods title=""/>
+      <packagestaticmethods title=""/>
+      <packageattributes title=""/>
+      <packagestaticattributes title=""/>
+      <properties title=""/>
+      <events title=""/>
+      <privatetypes title=""/>
+      <privateslots title=""/>
+      <privatemethods title=""/>
+      <privatestaticmethods title=""/>
+      <privateattributes title=""/>
+      <privatestaticattributes title=""/>
+      <friends title=""/>
+      <related title="" subtitle=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <services title=""/>
+      <interfaces title=""/>
+      <constructors title=""/>
+      <functions title=""/>
+      <related title=""/>
+      <variables title=""/>
+      <properties title=""/>
+      <events title=""/>
+    </memberdef>
+    <allmemberslink visible="yes"/>
+    <usedfiles visible="$SHOW_USED_FILES"/>
+    <authorsection visible="yes"/>
+  </class>
+
+  <!-- Layout definition for a namespace page -->
+  <namespace>
+    <briefdescription visible="yes"/>
+    <memberdecl>
+      <nestednamespaces visible="yes" title=""/>
+      <constantgroups visible="yes" title=""/>
+      <interfaces visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <concepts visible="yes" title=""/>
+      <structs visible="yes" title=""/>
+      <exceptions visible="yes" title=""/>
+      <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+    </memberdef>
+    <authorsection visible="yes"/>
+  </namespace>
+
+  <!-- Layout definition for a concept page -->
+  <concept>
+    <briefdescription visible="yes"/>
+    <includes visible="$SHOW_HEADERFILE"/>
+    <definition visible="yes" title=""/>
+    <detaileddescription title=""/>
+    <authorsection visible="yes"/>
+  </concept>
+
+  <!-- Layout definition for a file page -->
+  <file>
+    <briefdescription visible="yes"/>
+    <includes visible="$SHOW_INCLUDE_FILES"/>
+    <includegraph visible="yes"/>
+    <includedbygraph visible="yes"/>
+    <sourcelink visible="yes"/>
+    <memberdecl>
+      <interfaces visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <structs visible="yes" title=""/>
+      <exceptions visible="yes" title=""/>
+      <namespaces visible="yes" title=""/>
+      <concepts visible="yes" title=""/>
+      <constantgroups visible="yes" title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+    </memberdef>
+    <authorsection/>
+  </file>
+
+  <!-- Layout definition for a group page -->
+  <group>
+    <briefdescription visible="yes"/>
+    <groupgraph visible="yes"/>
+    <memberdecl>
+      <nestedgroups visible="yes" title=""/>
+      <modules visible="yes" title=""/>
+      <dirs visible="yes" title=""/>
+      <files visible="yes" title=""/>
+      <namespaces visible="yes" title=""/>
+      <concepts visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
+      <!-- <enums title=""/> -->
+      <!-- <enumvalues title=""/> -->
+      <functions title=""/>
+      <!-- <variables title=""/> -->
+      <signals title=""/>
+      <publicslots title=""/>
+      <protectedslots title=""/>
+      <privateslots title=""/>
+      <events title=""/>
+      <properties title=""/>
+      <friends title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <pagedocs/>
+      <inlineclasses title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
+      <enums title=""/>
+      <enumvalues title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <signals title=""/>
+      <publicslots title=""/>
+      <protectedslots title=""/>
+      <privateslots title=""/>
+      <events title=""/>
+      <properties title=""/>
+      <friends title=""/>
+    </memberdef>
+    <authorsection visible="yes"/>
+  </group>
+
+  <!-- Layout definition for a C++20 module page -->
+  <module>
+    <briefdescription visible="yes"/>
+    <exportedmodules visible="yes"/>
+    <memberdecl>
+      <concepts visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <enums title=""/>
+      <typedefs title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <membergroups title=""/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdecl>
+      <files visible="yes"/>
+    </memberdecl>
+  </module>
+
+  <!-- Layout definition for a directory page -->
+  <directory>
+    <briefdescription visible="yes"/>
+    <directorygraph visible="yes"/>
+    <memberdecl>
+      <dirs visible="yes"/>
+      <files visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+  </directory>
+</doxygenlayout>
diff --git a/examples/pktest.c b/examples/pktest.c
@@ -30,7 +30,6 @@ int main() {
 	cmd.code = PTP_OC_OpenSession;
 	cmd.params[0] = 1;
 	cmd.param_length = 1;
-	cmd.data_length = 0;
 
 	int l = ptp_new_cmd_packet(&r, &cmd);
 	print_bytes(r.data, l);

diff --git a/examples/usb.c b/examples/usb.c
@@ -1,4 +1,5 @@
-// Test device list API
+/// @file
+/// @brief Example of using the device list API
 #include <stdio.h>
 #include <stdint.h>
 #include <stdlib.h>
@@ -15,7 +16,7 @@ static int connect(struct PtpRuntime *r) {
 	}
 
 	if (ptp_device_init(r)) {
-		puts("Device connection error");
+		printf("Device connection error\n");
 		return 1;
 	}
 
@@ -27,11 +28,10 @@ static int connect(struct PtpRuntime *r) {
 }
 
 int main() {
-	struct PtpRuntime r;
-	ptp_generic_init(&r);
+	struct PtpRuntime *r = ptp_new(PTP_USB);
 
-	if (connect(&r)) return 1;
-	if (connect(&r)) return 1;
+	if (connect(r)) return 1;
+	if (connect(r)) return 1;
 
 	return 0;
 }

diff --git a/examples/wifi.c b/examples/wifi.c
@@ -1,4 +1,5 @@
-// Test basic opcode, get device properties
+/// @file
+/// @brief Hello
 #include <stdio.h>
 #include <stdint.h>
 #include <stdlib.h>
@@ -23,10 +24,8 @@ int main() {
 	r.connection_type = PTP_IP;
 
 	char *ip = "192.168.1.2";
-	ip = "127.0.0.1";
-	int port = PTP_IP_PORT;
 
-	if (ptpip_connect(&r, ip, port)) {
+	if (ptpip_connect(&r, ip, PTP_IP_PORT)) {
 		puts("Device connection error");
 		return 0;
 	}