Add mainpage, and fex useful pages, to generated documentation.

Doxyfile.in

@@ -97,15 +97,14 @@ INPUT                  = @top_srcdir@/src
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          = *.c \
                          *.h \
-                         *.C \
+                         *.dox
-                         *.H 
 RECURSIVE              = YES
 EXCLUDE                = 
 EXCLUDE_SYMLINKS       = NO
 EXCLUDE_PATTERNS       = */.svn/*
 EXCLUDE_SYMBOLS        = 
-EXAMPLE_PATH           = 
+EXAMPLE_PATH           = @top_srcdir@/ @top_srcdir@/src/examples/doc
-EXAMPLE_PATTERNS       = *
+EXAMPLE_PATTERNS       = ChangeLog *.c
 EXAMPLE_RECURSIVE      = NO
 IMAGE_PATH             = 
 INPUT_FILTER           = 

src/additional-pages.dox

@@ -0,0 +1,31 @@
+/** 
+ * @mainpage libnfc reference manual
+ *
+ * @section intro_sec Introduction
+ * This is the developer manual for \b libnfc.
+ * 
+ * @section quick_start_sec Quick start
+ * If you are looking for libnfc's public API, you should start with nfc.h
+ * Some commented examples that present how to use \b libnfc can be found here:
+ * @subpage examples_page
+ * 
+ * @section upgrading_sec Upgrading from previous version
+ * If you are upgrading from a previous \b libnfc version, please take care about changes, specially API changes.
+ * All important changes should be listed in @subpage changelog_page.
+ */
+
+/**
+ * @page examples_page Examples
+ * @section intro_sec Introduction
+ * This page present some examples to help developers which use \b libnfc.
+ *
+ * @section example_1_sec Simple tag UID reader.
+ * This short commented code example should be helpful to quick start development with \b libnfc, it grab the first available NFC device and print the first found ISO14443-A tag (e.g. MIFARE Classic, MIFARE Ultralight).
+ * @include quick_start_example1.c
+ */
+
+/**
+ * @page changelog_page ChangeLog from 1.2.1 to 1.3.0
+ * @verbinclude ChangeLog
+ */
+

src/examples/doc/quick_start_example1.c

@@ -0,0 +1,54 @@
+#include <stdlib.h>
+#include <nfc/nfc.h>
+
+int main(int argc, const char* argv[])
+{
+  nfc_device_t* pnd;
+  nfc_target_info_t nti;
+
+  // Display libnfc version
+  const char* acLibnfcVersion = nfc_version();
+  printf("%s use libnfc %s\n", argv[0], acLibnfcVersion);
+
+  // Connect using the first available NFC device
+  pnd = nfc_connect(NULL);
+
+  if (pnd == NULL) {
+      printf("Unable to connect to NFC device.");
+      return EXIT_FAILURE;
+  }
+
+  // Set connected NFC device to initiator mode
+  nfc_initiator_init(pnd);
+
+  // Drop the field for a while
+  nfc_configure(pnd,NDO_ACTIVATE_FIELD,false);
+
+  // Let the reader only try once to find a tag
+  nfc_configure(pnd,NDO_INFINITE_SELECT,false);
+
+  // Configure the CRC and Parity settings
+  nfc_configure(pnd,NDO_HANDLE_CRC,true);
+  nfc_configure(pnd,NDO_HANDLE_PARITY,true);
+
+  // Enable field so more power consuming cards can power themselves up
+  nfc_configure(pnd,NDO_ACTIVATE_FIELD,true);
+
+  printf("Connected to NFC reader: %s\n",pnd->acName);
+
+  // Poll for a ISO14443A (MIFARE) tag
+  if (nfc_initiator_select_tag(pnd,NM_ISO14443A_106,NULL,0,&nti)) {
+      printf("The following (NFC) ISO14443A tag was found:\n");
+      printf("    ATQA (SENS_RES): "); print_hex(nti.nai.abtAtqa,2);
+      printf("       UID (NFCID%c): ",(nti.nai.abtUid[0]==0x08?'3':'1')); print_hex(nti.nai.abtUid,nti.nai.szUidLen);
+      printf("      SAK (SEL_RES): "); print_hex(&nti.nai.btSak,1);
+      if (nti.nai.szAtsLen) {
+	  printf("          ATS (ATR): ");
+	  print_hex(nti.nai.abtAts,nti.nai.szAtsLen);
+      }
+  }
+
+  // Disconnect from NFC device
+  nfc_disconnect(pnd);
+  return EXIT_SUCCESS;
+}