From: Jelte Jansen <jeltejan@NLnetLabs.nl>
Date: Tue, 13 Jun 2006 13:17:30 +0000 (+0000)
Subject: and some more documentation
X-Git-Tag: release-1.1.0~85
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=cdc9a9218f22bf06a3aaeef3bc02e837ad93d18b;p=thirdparty%2Fldns.git

and some more documentation
---

diff --git a/ldns/buffer.h b/ldns/buffer.h
index ab7898c9..64637fb8 100644
--- a/ldns/buffer.h
+++ b/ldns/buffer.h
@@ -29,7 +29,13 @@
 #define LDNS_MIN_BUFLEN	256
 
 /**
- * LDNS implementation of buffers to ease operations
+ * \file buffer.h
+ *
+ * This file contains the definition of \ref ldns_buffer, and functions to manipulate those.
+ */
+
+/** 
+ * implementation of buffers to ease operations
  *
  * ldns_buffers can contain arbitrary information, per octet. You can write
  * to the current end of a buffer, read from the current position, and
diff --git a/ldns/common.h b/ldns/common.h
index 3b1eacea..8e09f3b0 100644
--- a/ldns/common.h
+++ b/ldns/common.h
@@ -1,8 +1,10 @@
-/*
- * common.h
+/**
+ * \file common.h
  *
  * Common definitions for LDNS
- *
+ */
+
+/**
  * a Net::DNS like library for C
  *
  * (c) NLnet Labs, 2004-2006
diff --git a/ldns/dname.h b/ldns/dname.h
index 31fe7598..e21c950f 100644
--- a/ldns/dname.h
+++ b/ldns/dname.h
@@ -10,6 +10,32 @@
  * See the file LICENSE for the license
  */
 
+/**
+ * \file dname.h
+ *
+ * dname contains function to read and manipulate domain names.
+ *
+ * Example domain names are "www.nlnetlabs.nl." and "." (the root)
+ *
+ * If a domain name ends with a dot ("."), it is called a Fully Qualified
+ * Domain Name (FQDN). In certain places (for instance when reading a zone
+ * file), an origin (which is just another domain name) non-FQDNs will be
+ * placed after the current. For instance, if i have a zone file where the
+ * origin has been set to "nl.", and my file contains the name
+ * "www.nlnetlabs", it will result in "www.nlnetlabs.nl.". Internally, dnames are
+ * always absolute (the dot is added when it is missing and there is no origin).
+ *
+ * An FQDN is also
+ * known as an absolute domain name, therefore the function to check this is
+ * called \ref ldns_dname_str_absolute
+ *
+ * Domain names are stored in \ref ldns_rdf structures, with the type
+ * \ref LDNS_RDF_TYPE_DNAME
+ * 
+ * This module is *NOT* about the RR type called DNAME.
+ */
+
+
 #ifndef LDNS_DNAME_H
 #define LDNS_DNAME_H
 
@@ -19,7 +45,7 @@
 #define LDNS_DNAME_NORMALIZE        tolower
 
 /**
- * concatenate two dnames together
+ * concatenates two dnames together
  * \param[in] rd1 the leftside
  * \param[in] rd2 the rightside
  * \return a new rdf with leftside/rightside
diff --git a/ldns/dns.h b/ldns/dns.h
index 7341f2a5..a17fde63 100644
--- a/ldns/dns.h
+++ b/ldns/dns.h
@@ -56,6 +56,13 @@ Or you can just use the menu above to browse through the API docs.
 \image html LogoInGradientBar2-y100.png
 </div>
 */
+
+/**
+ * \file dns.h
+ *
+ * Including this file will include all ldns files, and define some lookup tables.
+ */
+
 #ifndef LDNS_DNS_H
 #define LDNS_DNS_H
 
@@ -92,17 +99,19 @@ Or you can just use the menu above to browse through the API docs.
 
 /* lookup tables for standard DNS stuff  */
 
-/* Taken from RFC 2538, section 2.1.  */
+/** Taken from RFC 2538, section 2.1.  */
 extern ldns_lookup_table ldns_certificate_types[];
-/* Taken from RFC 2535, section 7.  */
+/** Taken from RFC 2535, section 7.  */
 extern ldns_lookup_table ldns_algorithms[];
-/* Taken from RFC 2538.  */
+/** Taken from RFC 2538.  */
 extern ldns_lookup_table ldns_cert_algorithms[];
-/* rr types  */
+/** rr types  */
 extern ldns_lookup_table ldns_rr_classes[];
-/* if these are used elsewhere */
+/** Response codes */
 extern ldns_lookup_table ldns_rcodes[];
+/** Operation codes */
 extern ldns_lookup_table ldns_opcodes[];
+/** EDNS flags */
 extern ldns_lookup_table ldns_edns_flags[];
 
 #endif /* LDNS_DNS_H */
diff --git a/ldns/dnssec.h b/ldns/dnssec.h
index 4452a180..3a1be9ff 100644
--- a/ldns/dnssec.h
+++ b/ldns/dnssec.h
@@ -8,6 +8,17 @@
  * A bunch of defines that are used in the DNS
  */
 
+/**
+ * \file dnssec.h
+ *
+ * This module contains functions for DNSSEC operations (RFC4033 t/m RFC4035).
+ * 
+ * Since those functions heavily rely op cryptographic operations, this module is
+ * dependent on openssl.
+ * 
+ */
+ 
+
 #ifndef LDNS_DNSSEC_H
 #define LDNS_DNSSEC_H
 
diff --git a/ldns/error.h b/ldns/error.h
index c5b54409..5e81d2fd 100644
--- a/ldns/error.h
+++ b/ldns/error.h
@@ -1,8 +1,11 @@
-/*
- * error.h
+/**
+ * \file error.h
  *
- * error reporting function and definition
+ * Defines error numbers and functions to translate those to a readable string.
  *
+ */
+ 
+/**
  * a Net::DNS like library for C
  *
  * (c) NLnet Labs, 2005-2006
diff --git a/ldns/higher.h b/ldns/higher.h
index 5ccb2bae..c98d013b 100644
--- a/ldns/higher.h
+++ b/ldns/higher.h
@@ -1,9 +1,11 @@
-/*
- * higher.h
- *
- * Specify some higher level functions that would
- * be usefull to would be developers
+/**
+ * \file higher.h
  *
+ * Specifies some higher level functions that could
+ * be useful for certain applications
+ */
+
+/*
  * a Net::DNS like library for C
  *
  * (c) NLnet Labs, 2005-2006
diff --git a/ldns/host2str.h b/ldns/host2str.h
index 58abbdac..09108319 100644
--- a/ldns/host2str.h
+++ b/ldns/host2str.h
@@ -8,6 +8,13 @@
  * See the file LICENSE for the license
  */
 
+/**
+ * \file
+ *
+ * Contains functions to translate the main structures to their text
+ * representation, as well as functions to print them.
+ */
+
 #ifndef LDNS_HOST2STR_H
 #define LDNS_HOST2STR_H
 
diff --git a/ldns/host2wire.h b/ldns/host2wire.h
index 4b6f211e..0e483614 100644
--- a/ldns/host2wire.h
+++ b/ldns/host2wire.h
@@ -8,6 +8,12 @@
  * See the file LICENSE for the license
  */
 
+/**
+ * \file
+ *
+ * Contains all functions to translate the main structures to wire format
+ */
+
 #ifndef LDNS_HOST2WIRE_H
 #define LDNS_HOST2WIRE_H
 
diff --git a/ldns/keys.h b/ldns/keys.h
index 754a101b..1da1771e 100644
--- a/ldns/keys.h
+++ b/ldns/keys.h
@@ -11,6 +11,13 @@
  * See the file LICENSE for the license
  */
 
+/**
+ * \file
+ *
+ * Addendum to \ref dnssec.h, this module contains key and algorithm definitions and functions.
+ */
+ 
+
 #ifndef LDNS_KEYS_H
 #define LDNS_KEYS_H
 
diff --git a/ldns/net.h b/ldns/net.h
index eb60b617..3709c104 100644
--- a/ldns/net.h
+++ b/ldns/net.h
@@ -23,6 +23,11 @@
 #define LDNS_DEFAULT_TIMEOUT_SEC 2
 #define LDNS_DEFAULT_TIMEOUT_USEC 0
 
+/**
+ * \file
+ *
+ * Contains functions to send and receive packets over a network.
+ */
 
 /**
  * Sends a buffer to an ip using udp and return the respons as a ldns_pkt
diff --git a/ldns/packet.h b/ldns/packet.h
index a4e13bd5..7a039222 100644
--- a/ldns/packet.h
+++ b/ldns/packet.h
@@ -10,6 +10,14 @@
  * See the file LICENSE for the license
  */
 
+/**
+ * \file
+ *
+ * Contains the definition of \ref ldns_pkt and its parts, as well
+ * as functions to manipulate those.
+ */
+
+
 #ifndef LDNS_PACKET_H
 #define LDNS_PACKET_H