From: Miek Gieben <miekg@NLnetLabs.nl>
Date: Mon, 23 Jan 2006 11:28:51 +0000 (+0000)
Subject: more documentation updates
X-Git-Tag: release-1.1.0~403
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=878a750f3ae331d28db4e7c694f30f3e6bf28be7;p=thirdparty%2Fldns.git

more documentation updates
---

diff --git a/TODO-DOCS b/TODO-DOCS
index 027ca34c..eb43c716 100644
--- a/TODO-DOCS
+++ b/TODO-DOCS
@@ -1,6 +1,4 @@
 update.h   - all
-resolver.h - only set
 packet.h   - get/set
 keys.h     - get/set
-dnssec.h   - some + get/set
-buffer.h   - docs are there, but need to be doxygened
+buffer.h   - half way through
diff --git a/doc/function_manpages b/doc/function_manpages
index c7f8094e..19f9c9c1 100644
--- a/doc/function_manpages
+++ b/doc/function_manpages
@@ -2,17 +2,22 @@
 # other names are aliases (symlinks)
 # all functions specified on the same line are included in the
 # same manual page
+# function named after the pipe `|' are put in the see also section
 
 # functions that must be included, separated by commas
 
 ### host2wire.h
 # conversion functions
-ldns_rr2wire, ldns_pkt2wire, ldns_rdf2wire, ldns_rr2str, ldns_pkt2str, ldns_rdf2str
-
+ldns_rr2wire, ldns_pkt2wire, ldns_rdf2wire
 # lower level conversions, some are from host2str.h
 ldns_pkt2buffer_str, ldns_pktheader2buffer_str, ldns_rr2buffer_str, ldns_rr_list2buffer_str, ldns_rdf2buffer_str, ldns_key2buffer_str, ldns_pkt2buffer_wire, ldns_rr2buffer_wire, ldns_rdf2buffer_wire, ldns_rrsig2buffer_wire, ldns_rr_rdata2buffer_wire
 ### /host2wire.h
 
+### host2str.h
+ldns_rr2str, ldns_pkt2str, ldns_rdf2str, ldns_rr_list2str, ldns_key2str
+ldns_rr_print, ldns_rdf_print, ldns_pkt_print, ldns_rr_list_print, ldns_resolver_print, ldns_zone_print
+### /host2str.h
+
 ### host2str.h
 # and even lower
 ldns_rdf2buffer_str_a, ldns_rdf2buffer_str_aaaa, ldns_rdf2buffer_str_str, ldns_rdf2buffer_str_b64, ldns_rdf2buffer_str_hex, ldns_rdf2buffer_str_type, ldns_rdf2buffer_str_class, ldns_rdf2buffer_str_alg, ldns_rdf2buffer_str_cert, ldns_rdf2buffer_str_loc, ldns_rdf2buffer_str_unknown, ldns_rdf2buffer_str_nsap, ldns_rdf2buffer_str_wks, ldns_rdf2buffer_str_nsec, ldns_rdf2buffer_str_period, ldns_rdf2buffer_str_tsigtime, ldns_rdf2buffer_str_apl, ldns_rdf2buffer_str_int16_data, ldns_rdf2buffer_str_int16, ldns_rdf2buffer_str_ipseckey
@@ -37,7 +42,7 @@ ldns_rdf, ldns_rdf_type | ldns_rdf_set_size, ldns_rdf_size, ldns_rdf_new, ldns_n
 ldns_rdf_set_size, ldns_rdf_set_type, ldns_rdf_set_data | ldns_rdf
 ldns_rdf_size, ldns_rdf_get_type, ldns_rdf_data | ldns_rdf
 ldns_rdf_new, ldns_rdf_new_frm_data, ldns_rdf_new_frm_str, ldns_rdf_new_frm_fp, ldns_rdf_free, ldns_rdf_deep_free, ldns_rdf_print | ldns_rdf
-ldns_native2rdf_int8, ldns_native2rdf_int16, ldns_native2rdf_int32,ldns_native2rdf_int16_data, ldns_rdf2native_int8, ldns_rdf2native_int16, ldns_rdf2native_int32, ldns_rdf2native_sockaddr_storage | ldns_rdf
+ldns_native2rdf_int8, ldns_native2rdf_int16, ldns_native2rdf_int32,ldns_native2rdf_int16_data, ldns_rdf2native_int8, ldns_rdf2native_int16, ldns_rdf2native_int32, ldns_rdf2native_sockaddr_storage, ldns_rdf2native_time_t | ldns_rdf
 ldns_rdf_address_reverse | ldns_rdf
 ldns_octet | ldns_rdf
 # why is this in rdata.h?
@@ -65,11 +70,11 @@ ldns_verify, ldns_verify_rrsig, ldns_verify_rrsig_keylist | ldns_verify_rrsig_ds
 ldns_key_buf2dsa, ldns_key_buf2rsa | ldns_key_rr2ds
 ldns_key_rr2ds
 # signing
-ldns_sign_public | ldns_sign_public_dsa, ldns_sign_public_rsamd5, ldns_sign_public_rsasha1, ldns_sign_public_dsa
-ldns_sign_public_dsa, ldns_sign_public_rsamd5, ldns_sign_public_rsasha1, ldns_sign_public_dsa
-ldns_zone_sign
+ldns_sign_public | ldns_sign_public_dsa, ldns_sign_public_rsamd5, ldns_sign_public_rsasha1
+ldns_sign_public_dsa, ldns_sign_public_rsamd5, ldns_sign_public_rsasha1
+ldns_zone_sign | ldns_sign_public
 ldns_init_random
-#ldns_pkt_verify
+ldns_pkt_verify | ldns_verify
 ### /dnssec.h
 
 ### dnskey.h
diff --git a/ldns/buffer.h b/ldns/buffer.h
index 70bbb43a..42b6716e 100644
--- a/ldns/buffer.h
+++ b/ldns/buffer.h
@@ -92,6 +92,7 @@ void ldns_buffer_new_frm_data(ldns_buffer *buffer, void *data, size_t size);
 /**
  * clears the buffer and make it ready for writing.  The buffer's limit
  * is set to the capacity and the position is set to 0.
+ * \param[in] buffer the buffer to clear
  */
 void ldns_buffer_clear(ldns_buffer *buffer);
 
@@ -108,11 +109,14 @@ void ldns_buffer_flip(ldns_buffer *buffer);
 /**
  * make the buffer ready for re-reading the data.  The buffer's
  * position is reset to 0.
+ * \param[in] buffer the buffer to rewind
  */
 void ldns_buffer_rewind(ldns_buffer *buffer);
 
 /**
  * returns the current position in the buffer (as a number of bytes)
+ * \param[in] buffer the buffer
+ * \return the current position
  */
 INLINE size_t
 ldns_buffer_position(ldns_buffer *buffer)
@@ -123,6 +127,8 @@ ldns_buffer_position(ldns_buffer *buffer)
 /**
  * sets the buffer's position to MARK.  The position must be less than
  * or equal to the buffer's limit.
+ * \param[in] buffer the buffer
+ * \param[in] mark the mark to use
  */
 INLINE void
 ldns_buffer_set_position(ldns_buffer *buffer, size_t mark)
@@ -135,6 +141,8 @@ ldns_buffer_set_position(ldns_buffer *buffer, size_t mark)
  * changes the buffer's position by COUNT bytes.  The position must not
  * be moved behind the buffer's limit or before the beginning of the
  * buffer.
+ * \param[in] buffer the buffer
+ * \param[in] count the count to use
  */
 INLINE void
 ldns_buffer_skip(ldns_buffer *buffer, ssize_t count)
@@ -145,6 +153,8 @@ ldns_buffer_skip(ldns_buffer *buffer, ssize_t count)
 
 /**
  * returns the maximum size of the buffer
+ * \param[in] buffer
+ * \return the size
  */
 INLINE size_t
 ldns_buffer_limit(ldns_buffer *buffer)
@@ -155,6 +165,8 @@ ldns_buffer_limit(ldns_buffer *buffer)
 /**
  * changes the buffer's limit.  If the buffer's position is greater
  * than the new limit the position is set to the limit.
+ * \param[in] buffer the buffer
+ * \param[in] limit the new limit
  */
 INLINE void
 ldns_buffer_set_limit(ldns_buffer *buffer, size_t limit)
@@ -167,6 +179,8 @@ ldns_buffer_set_limit(ldns_buffer *buffer, size_t limit)
 
 /**
  * returns the number of bytes the buffer can hold.
+ * \param[in] buffer the buffer
+ * \return the number of bytes
  */
 INLINE size_t
 ldns_buffer_capacity(ldns_buffer *buffer)
@@ -178,6 +192,9 @@ ldns_buffer_capacity(ldns_buffer *buffer)
  * changes the buffer's capacity.  The data is reallocated so any
  * pointers to the data may become invalid.  The buffer's limit is set
  * to the buffer's new capacity.
+ * \param[in] buffer the buffer
+ * \param[in] capacity the capacity to use
+ * \return whether this failed or succeeded
  */
 bool ldns_buffer_set_capacity(ldns_buffer *buffer, size_t capacity);
 
@@ -187,11 +204,17 @@ bool ldns_buffer_set_capacity(ldns_buffer *buffer, size_t capacity);
  *
  * The buffer's limit is always set to the (possibly increased)
  * capacity.
+ * \param[in] buffer the buffer
+ * \param[in] amount amount to use
+ * \return whether this failed or succeeded
  */
 bool ldns_buffer_reserve(ldns_buffer *buffer, size_t amount);
 
 /**
  * returns a pointer to the data at the indicated position.
+ * \param[in] buffer the buffer
+ * \param[in] at position
+ * \return the pointer to the data
  */
 INLINE uint8_t *
 ldns_buffer_at(ldns_buffer *buffer, size_t at)
@@ -203,6 +226,8 @@ ldns_buffer_at(ldns_buffer *buffer, size_t at)
 /**
  * returns a pointer to the beginning of the buffer (the data at
  * position 0).
+ * \param[in] buffer the buffer
+ * \return the pointer
  */
 INLINE uint8_t *
 ldns_buffer_begin(ldns_buffer *buffer)
@@ -213,6 +238,8 @@ ldns_buffer_begin(ldns_buffer *buffer)
 /**
  * returns a pointer to the end of the buffer (the data at the buffer's
  * limit).
+ * \param[in] buffer the buffer
+ * \return the pointer
  */
 INLINE uint8_t *
 ldns_buffer_end(ldns_buffer *buffer)
@@ -222,6 +249,8 @@ ldns_buffer_end(ldns_buffer *buffer)
 
 /**
  * returns a pointer to the data at the buffer's current position.
+ * \param[in] buffer the buffer
+ * \return the pointer
  */
 INLINE uint8_t *
 ldns_buffer_current(ldns_buffer *buffer)
@@ -232,6 +261,9 @@ ldns_buffer_current(ldns_buffer *buffer)
 /**
  * returns the number of bytes remaining between the indicated position and
  * the limit.
+ * \param[in] buffer the buffer
+ * \param[in] at indicated position
+ * \return number of bytes
  */
 INLINE size_t
 ldns_buffer_remaining_at(ldns_buffer *buffer, size_t at)
@@ -244,6 +276,8 @@ ldns_buffer_remaining_at(ldns_buffer *buffer, size_t at)
 /**
  * returns the number of bytes remaining between the buffer's position and
  * limit.
+ * \param[in] buffer the buffer
+ * \return the number of bytes
  */
 INLINE size_t
 ldns_buffer_remaining(ldns_buffer *buffer)
@@ -255,6 +289,10 @@ ldns_buffer_remaining(ldns_buffer *buffer)
  * checks if the buffer has at least COUNT more bytes available.
  * Before reading or writing the caller needs to ensure enough space
  * is available!
+ * \param[in] buffer the buffer
+ * \param[in] at indicated position
+ * \param[in] count how much is available
+ * \return true or false (as int?)
  */
 INLINE int
 ldns_buffer_available_at(ldns_buffer *buffer, size_t at, size_t count)
@@ -264,6 +302,9 @@ ldns_buffer_available_at(ldns_buffer *buffer, size_t at, size_t count)
 
 /**
  * checks if the buffer has count bytes available at the current position
+ * \param[in] buffer the buffer
+ * \param[in] count how much is available
+ * \return true or false (as int?)
  */
 INLINE int
 ldns_buffer_available(ldns_buffer *buffer, size_t count)
@@ -273,7 +314,7 @@ ldns_buffer_available(ldns_buffer *buffer, size_t count)
 
 /**
  * writes the given data to the buffer at the specified position
- *
+ * \param[in] buffer the buffer
  * \param[in] at the position (in number of bytes) to write the data at
  * \param[in] data pointer to the data to write to the buffer
  * \param[in] count the number of bytes of data to write
@@ -287,6 +328,7 @@ ldns_buffer_write_at(ldns_buffer *buffer, size_t at, const void *data, size_t co
 
 /**
  * writes count bytes of data to the current position of the buffer
+ * 
  */
 INLINE void
 ldns_buffer_write(ldns_buffer *buffer, const void *data, size_t count)
diff --git a/ldns/dnssec.h b/ldns/dnssec.h
index 6f2ed160..3406f159 100644
--- a/ldns/dnssec.h
+++ b/ldns/dnssec.h
@@ -53,7 +53,13 @@ ldns_status ldns_verify(ldns_rr_list *rrset, ldns_rr_list *rrsig, ldns_rr_list *
  */
 ldns_status ldns_verify_rrsig_keylist(ldns_rr_list *rrset, ldns_rr *rrsig, ldns_rr_list *keys, ldns_rr_list *good_keys);
 
-
+/**
+ * verify an rrsig with 1 key
+ * \param[in] rrset the rrset
+ * \param[in] rrsig the rrsig to verify
+ * \param[in] key the key to use
+ * \return status message wether verification succeeded.
+ */
 ldns_status ldns_verify_rrsig(ldns_rr_list *rrset, ldns_rr *rrsig, ldns_rr *key);
 
 /**
@@ -84,23 +90,23 @@ ldns_status ldns_verify_rrsig_rsasha1(ldns_buffer *sig, ldns_buffer *rrset, ldns
  */
 ldns_status ldns_verify_rrsig_rsamd5(ldns_buffer *sig, ldns_buffer *rrset, ldns_buffer *key);
 
+#ifdef HAVE_SSL
 /**
  * converts a buffer holding key material to a DSA key in openssl.
  *
  * \param[in] key the key to convert
  * \return a DSA * structure with the key material
  */
-#ifdef HAVE_SSL
 DSA *ldns_key_buf2dsa(ldns_buffer *key);
 #endif /* HAVE_SSL */
 
+#ifdef HAVE_SSL
 /**
  * converts a buffer holding key material to a RSA key in openssl.
  *
  * \param[in] key the key to convert
  * \return a RSA * structure with the key material
  */
-#ifdef HAVE_SSL
 RSA *ldns_key_buf2rsa(ldns_buffer *key);
 #endif /* HAVE_SSL */
 
@@ -112,11 +118,37 @@ RSA *ldns_key_buf2rsa(ldns_buffer *key);
  */
 ldns_rr *ldns_key_rr2ds(const ldns_rr *key);
 
-/* sign functions - these are very much a work in progress */
+/* sign functions */
+
+/**
+ * Sign an rrset
+ * \param[in] rrset the rrset
+ * \param[in] keys the keys to use
+ * \return a rr_list with the signatures
+ */
 ldns_rr_list *ldns_sign_public(ldns_rr_list *rrset, ldns_key_list *keys);
+
 #ifdef HAVE_SSL
+/**
+ * Sign a buffer with the DSA key (hash with SHA1)
+ * \param[in] to_sign buffer with the data
+ * \param[in] key the key to use
+ * \return a ldns_rdf with the signed data
+ */
 ldns_rdf *ldns_sign_public_dsa(ldns_buffer *to_sign, DSA *key);
+/**
+ * Sign a buffer with the RSA key (hash with MD5)
+ * \param[in] to_sign buffer with the data
+ * \param[in] key the key to use
+ * \return a ldns_rdf with the signed data
+ */
 ldns_rdf *ldns_sign_public_rsamd5(ldns_buffer *to_sign, RSA *key);
+/**
+ * Sign a buffer with the RSA key (hash with SHA1)
+ * \param[in] to_sign buffer with the data
+ * \param[in] key the key to use
+ * \return a ldns_rdf with the signed data
+ */
 ldns_rdf *ldns_sign_public_rsasha1(ldns_buffer *to_sign, RSA *key);
 #endif /* HAVE_SSL */
 
@@ -130,7 +162,15 @@ ldns_rdf *ldns_sign_public_rsasha1(ldns_buffer *to_sign, RSA *key);
 ldns_rr * ldns_create_nsec(ldns_rdf *cur_owner, ldns_rdf *next_owner, ldns_rr_list *rrs);
 
 /**
- *
+ * verify a packet 
+ * \param[in] p the packet
+ * \param[in] t the rr set type to check
+ * \param[in] o the rr set name to ckeck
+ * \param[in] k list of keys
+ * \param[in] s list of sigs (may be null)
+ * \param[out] good_keys keys which validated the packet
+ * \return status 
+ * 
  */
 ldns_status ldns_pkt_verify(ldns_pkt *p, ldns_rr_type t, ldns_rdf *o, ldns_rr_list *k, ldns_rr_list *s, ldns_rr_list *good_keys);