From: Miek Gieben <miekg@NLnetLabs.nl>
Date: Tue, 24 Jan 2006 09:10:09 +0000 (+0000)
Subject: documentation updates
X-Git-Tag: release-1.1.0~398
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2c4aff04a2b11bc46d632b84f2dcfa926e251b37;p=thirdparty%2Fldns.git

documentation updates
---

diff --git a/TODO b/TODO
index a651d37b..8621d984 100644
--- a/TODO
+++ b/TODO
@@ -24,7 +24,6 @@ Post 1.0 Stuff:
 1.1.0:
 ----
         o server stuff yes/no
-        o documentation
         o sorting/sorting ord - removed ord - need to check current sort
           order
         o secure tracing drill
diff --git a/TODO-DOCS b/TODO-DOCS
index 78e220bc..e0e6ca72 100644
--- a/TODO-DOCS
+++ b/TODO-DOCS
@@ -1,4 +1 @@
-update.h   - still 2 to go 
-packet.h   - get/set
 keys.h     - get/set
-buffer.h   - half way through
diff --git a/ldns/buffer.h b/ldns/buffer.h
index 42b6716e..cb5c476f 100644
--- a/ldns/buffer.h
+++ b/ldns/buffer.h
@@ -328,7 +328,9 @@ 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
- * 
+ * \param[in] buffer the buffer
+ * \param[in] data the data to write
+ * \param[in] count the lenght of the data to write
  */
 INLINE void
 ldns_buffer_write(ldns_buffer *buffer, const void *data, size_t count)
@@ -339,6 +341,9 @@ ldns_buffer_write(ldns_buffer *buffer, const void *data, size_t count)
 
 /**
  * copies the given (null-delimited) string to the specified position at the buffer
+ * \param[in] buffer the buffer
+ * \param[in] at the position in the buffer
+ * \param[in] str the string to write
  */
 INLINE void
 ldns_buffer_write_string_at(ldns_buffer *buffer, size_t at, const char *str)
@@ -348,6 +353,8 @@ ldns_buffer_write_string_at(ldns_buffer *buffer, size_t at, const char *str)
 
 /**
  * copies the given (null-delimited) string to the current position at the buffer
+ * \param[in] buffer the buffer
+ * \param[in] str the string to write
  */
 INLINE void
 ldns_buffer_write_string(ldns_buffer *buffer, const char *str)
@@ -357,6 +364,9 @@ ldns_buffer_write_string(ldns_buffer *buffer, const char *str)
 
 /**
  * writes the given byte of data at the given position in the buffer
+ * \param[in] buffer the buffer
+ * \param[in] at the position in the buffer
+ * \param[in] data the 8 bits to write
  */
 INLINE void
 ldns_buffer_write_u8_at(ldns_buffer *buffer, size_t at, uint8_t data)
@@ -367,6 +377,8 @@ ldns_buffer_write_u8_at(ldns_buffer *buffer, size_t at, uint8_t data)
 
 /**
  * writes the given byte of data at the current position in the buffer
+ * \param[in] buffer the buffer
+ * \param[in] data the 8 bits to write
  */
 INLINE void
 ldns_buffer_write_u8(ldns_buffer *buffer, uint8_t data)
@@ -377,6 +389,9 @@ ldns_buffer_write_u8(ldns_buffer *buffer, uint8_t data)
 
 /**
  * writes the given 2 byte integer at the given position in the buffer
+ * \param[in] buffer the buffer
+ * \param[in] at the position in the buffer
+ * \param[in] data the 16 bits to write
  */
 INLINE void
 ldns_buffer_write_u16_at(ldns_buffer *buffer, size_t at, uint16_t data)
@@ -387,6 +402,8 @@ ldns_buffer_write_u16_at(ldns_buffer *buffer, size_t at, uint16_t data)
 
 /**
  * writes the given 2 byte integer at the current position in the buffer
+ * \param[in] buffer the buffer
+ * \param[in] data the 16 bits to write
  */
 INLINE void
 ldns_buffer_write_u16(ldns_buffer *buffer, uint16_t data)
@@ -397,6 +414,9 @@ ldns_buffer_write_u16(ldns_buffer *buffer, uint16_t data)
 
 /**
  * writes the given 4 byte integer at the given position in the buffer
+ * \param[in] buffer the buffer
+ * \param[in] at the position in the buffer
+ * \param[in] data the 32 bits to write
  */
 INLINE void
 ldns_buffer_write_u32_at(ldns_buffer *buffer, size_t at, uint32_t data)
@@ -407,6 +427,8 @@ ldns_buffer_write_u32_at(ldns_buffer *buffer, size_t at, uint32_t data)
 
 /**
  * writes the given 4 byte integer at the current position in the buffer
+ * \param[in] buffer the buffer
+ * \param[in] data the 32 bits to write
  */
 INLINE void
 ldns_buffer_write_u32(ldns_buffer *buffer, uint32_t data)
@@ -417,6 +439,10 @@ ldns_buffer_write_u32(ldns_buffer *buffer, uint32_t data)
 
 /**
  * copies count bytes of data at the given position to the given data-array
+ * \param[in] buffer the buffer
+ * \param[in] at the position in the buffer to start
+ * \param[out] data buffer to copy to
+ * \param[in] count the length of the data to copy
  */
 INLINE void
 ldns_buffer_read_at(ldns_buffer *buffer, size_t at, void *data, size_t count)
@@ -427,6 +453,9 @@ ldns_buffer_read_at(ldns_buffer *buffer, size_t at, void *data, size_t count)
 
 /**
  * copies count bytes of data at the current position to the given data-array
+ * \param[in] buffer the buffer
+ * \param[out] data buffer to copy to
+ * \param[in] count the length of the data to copy
  */
 INLINE void
 ldns_buffer_read(ldns_buffer *buffer, void *data, size_t count)
@@ -437,6 +466,9 @@ ldns_buffer_read(ldns_buffer *buffer, void *data, size_t count)
 
 /**
  * returns the byte value at the given position in the buffer
+ * \param[in] buffer the buffer
+ * \param[in] at the position in the buffer
+ * \return 1 byte integer
  */
 INLINE uint8_t
 ldns_buffer_read_u8_at(ldns_buffer *buffer, size_t at)
@@ -447,6 +479,8 @@ ldns_buffer_read_u8_at(ldns_buffer *buffer, size_t at)
 
 /**
  * returns the byte value at the current position in the buffer
+ * \param[in] buffer the buffer
+ * \return 1 byte integer
  */
 INLINE uint8_t
 ldns_buffer_read_u8(ldns_buffer *buffer)
@@ -458,6 +492,9 @@ ldns_buffer_read_u8(ldns_buffer *buffer)
 
 /**
  * returns the 2-byte integer value at the given position in the buffer
+ * \param[in] buffer the buffer
+ * \param[in] at position in the buffer
+ * \return 2 byte integer
  */
 INLINE uint16_t
 ldns_buffer_read_u16_at(ldns_buffer *buffer, size_t at)
@@ -468,6 +505,8 @@ ldns_buffer_read_u16_at(ldns_buffer *buffer, size_t at)
 
 /**
  * returns the 2-byte integer value at the current position in the buffer
+ * \param[in] buffer the buffer
+ * \return 2 byte integer
  */
 INLINE uint16_t
 ldns_buffer_read_u16(ldns_buffer *buffer)
@@ -479,6 +518,9 @@ ldns_buffer_read_u16(ldns_buffer *buffer)
 
 /**
  * returns the 4-byte integer value at the given position in the buffer
+ * \param[in] buffer the buffer
+ * \param[in] at position in the buffer
+ * \return 4 byte integer
  */
 INLINE uint32_t
 ldns_buffer_read_u32_at(ldns_buffer *buffer, size_t at)
@@ -489,6 +531,8 @@ ldns_buffer_read_u32_at(ldns_buffer *buffer, size_t at)
 
 /**
  * returns the 4-byte integer value at the current position in the buffer
+ * \param[in] buffer the buffer
+ * \return 4 byte integer
  */
 INLINE uint32_t
 ldns_buffer_read_u32(ldns_buffer *buffer)
@@ -500,6 +544,8 @@ ldns_buffer_read_u32(ldns_buffer *buffer)
 
 /**
  * returns the status of the buffer
+ * \param[in] buffer
+ * \return the status
  */
 INLINE ldns_status
 ldns_buffer_status(ldns_buffer *buffer)
@@ -509,6 +555,8 @@ ldns_buffer_status(ldns_buffer *buffer)
 
 /**
  * returns true if the status of the buffer is LDNS_STATUS_OK, false otherwise
+ * \param[in] buffer the buffer
+ * \return true or false
  */
 INLINE bool
 ldns_buffer_status_ok(ldns_buffer *buffer)
diff --git a/ldns/packet.h b/ldns/packet.h
index 5580114b..3633b8b0 100644
--- a/ldns/packet.h
+++ b/ldns/packet.h
@@ -91,6 +91,7 @@ struct ldns_struct_pkt
 	uint16_t _answersize;
 	ldns_rdf *_answerfrom;
 	char *_when;
+        /** timestamp of when the packet was sent */
 	struct timeval timestamp;
 	/**  query duration */
 	uint32_t _querytime;
@@ -204,21 +205,102 @@ bool ldns_pkt_ad(const ldns_pkt *p);
  * \return the opcode
  */
 ldns_pkt_opcode ldns_pkt_get_opcode(const ldns_pkt *p);
+
+/**
+ * Return the packet's respons code
+ * \param[in] p the packet
+ * \return the respons code
+ */
 uint8_t ldns_pkt_rcode(const ldns_pkt *p);
+/**
+ * Return the packet's qd count 
+ * \param[in] p the packet
+ * \return the qd count
+ */
 uint16_t ldns_pkt_qdcount(const ldns_pkt *p);
+/**
+ * Return the packet's an count
+ * \param[in] p the packet
+ * \return the an count
+ */
 uint16_t ldns_pkt_ancount(const ldns_pkt *p);
+/**
+ * Return the packet's ns count
+ * \param[in] p the packet
+ * \return the ns count
+ */
 uint16_t ldns_pkt_nscount(const ldns_pkt *p);
+/**
+ * Return the packet's ar count
+ * \param[in] p the packet
+ * \return the ar count
+ */
 uint16_t ldns_pkt_arcount(const ldns_pkt *p);
+
+/** 
+ * Return the packet's answerfrom
+ * \param[in] p packet
+ * \return the name of the server
+ */
 ldns_rdf *ldns_pkt_answerfrom(const ldns_pkt *p);
+
+/** 
+ * Return the packet's date of sending
+ * \param[in] p packet
+ * \return the time in ascii
+ */
 char *ldns_pkt_when(const ldns_pkt *p);
+
+/**
+ * Return the packet's timestamp
+ * \param[in] p the packet
+ * \return the timestamp
+ */
 struct timeval ldns_pkt_timestamp(const ldns_pkt *p);
+/**
+ * Return the packet's querytime
+ * \param[in] p the packet
+ * \return the querytime
+ */
 uint32_t ldns_pkt_querytime(const ldns_pkt *p);
+
+/**
+ * Return the packet's size in bytes
+ * \param[in] p the packet
+ * \return the size
+ */
 size_t ldns_pkt_size(const ldns_pkt *p);
+
+/**
+ * Return the packet's tsig pseudo rr's
+ * \param[in] p the packet
+ * \return the tsig rr
+ */
 ldns_rr *ldns_pkt_tsig(const ldns_pkt *p);
 
+/**
+ * Return the packet's question section
+ * \param[in] p the packet
+ * \return the section
+ */
 ldns_rr_list *ldns_pkt_question(const ldns_pkt *p);
+/**
+ * Return the packet's answer section
+ * \param[in] p the packet
+ * \return the section
+ */
 ldns_rr_list *ldns_pkt_answer(const ldns_pkt *p);
+/**
+ * Return the packet's authority section
+ * \param[in] p the packet
+ * \return the section
+ */
 ldns_rr_list *ldns_pkt_authority(const ldns_pkt *p);
+/**
+ * Return the packet's additional section
+ * \param[in] p the packet
+ * \return the section
+ */
 ldns_rr_list *ldns_pkt_additional(const ldns_pkt *p);
 
 /**
@@ -230,8 +312,33 @@ ldns_rr_list *ldns_pkt_additional(const ldns_pkt *p);
  */
 ldns_rr_list *ldns_pkt_get_section_clone(ldns_pkt *p, ldns_pkt_section s);
 
+/**
+ * return all the rr with a specific name from a packet. Optionally
+ * specify from which section in the packet
+ * \param[in] p the packet
+ * \param[in] r the name
+ * \param[in] s the packet's section
+ * \return a list with the rr's or NULL if none were found
+ */
 ldns_rr_list *ldns_pkt_rr_list_by_name(ldns_pkt *p, ldns_rdf *r, ldns_pkt_section s);
+/**
+ * return all the rr with a specific type from a packet. Optionally
+ * specify from which section in the packet
+ * \param[in] p the packet
+ * \param[in] t the type
+ * \param[in] s the packet's section
+ * \return a list with the rr's or NULL if none were found
+ */
 ldns_rr_list *ldns_pkt_rr_list_by_type(ldns_pkt *p, ldns_rr_type t, ldns_pkt_section s);
+/**
+ * return all the rr with a specific type and type from a packet. Optionally
+ * specify from which section in the packet
+ * \param[in] packet the packet
+ * \param[in] ownername the name
+ * \param[in] type the type
+ * \param[in] sec the packet's section
+ * \return a list with the rr's or NULL if none were found
+ */
 ldns_rr_list *ldns_pkt_rr_list_by_name_and_type(ldns_pkt *packet, ldns_rdf *ownername, ldns_rr_type type, ldns_pkt_section sec);
 
 /**
@@ -296,18 +403,84 @@ void ldns_pkt_set_ra(ldns_pkt *p, bool b);
  */
 void ldns_pkt_set_ad(ldns_pkt *p, bool b);
 
+/**
+ * Set the packet's opcode
+ * \param[in] p the packet
+ * \param[in] c the opcode
+ */
 void ldns_pkt_set_opcode(ldns_pkt *p, ldns_pkt_opcode c);
+/**
+ * Set the packet's respons code
+ * \param[in] p the packet
+ * \param[in] c the rcode
+ */
 void ldns_pkt_set_rcode(ldns_pkt *p, uint8_t c);
+/**
+ * Set the packet's qd count
+ * \param[in] p the packet
+ * \param[in] c the count
+ */
 void ldns_pkt_set_qdcount(ldns_pkt *p, uint16_t c);
+/**
+ * Set the packet's an count
+ * \param[in] p the packet
+ * \param[in] c the count
+ */
 void ldns_pkt_set_ancount(ldns_pkt *p, uint16_t c);
+/**
+ * Set the packet's ns count
+ * \param[in] p the packet
+ * \param[in] c the count
+ */
 void ldns_pkt_set_nscount(ldns_pkt *p, uint16_t c);
+/**
+ * Set the packet's arcount
+ * \param[in] p the packet
+ * \param[in] c the count
+ */
 void ldns_pkt_set_arcount(ldns_pkt *p, uint16_t c);
+/**
+ * Set the packet's answering server
+ * \param[in] p the packet
+ * \param[in] r the address
+ */
 void ldns_pkt_set_answerfrom(ldns_pkt *p, ldns_rdf *r);
+/**
+ * Set the packet's query time
+ * \param[in] p the packet
+ * \param[in] t the querytime in msec
+ */
 void ldns_pkt_set_querytime(ldns_pkt *p, uint32_t t);
+/**
+ * Set the packet's size
+ * \param[in] p the packet
+ * \param[in] s the size
+ */
 void ldns_pkt_set_size(ldns_pkt *p, size_t s);
+/**
+ * Set the packet's when string
+ * \param[in] p the packet
+ * \param[in] w the string with the date
+ */
 void ldns_pkt_set_when(ldns_pkt *p, char *w);
+/**
+ * Set the packet's timestamp
+ * \param[in] p the packet
+ * \param[in] timeval the timestamp
+ */
 void ldns_pkt_set_timestamp(ldns_pkt *p, struct timeval);
+/**
+ * Set a packet's section count to x
+ * \param[in] p the packet
+ * \param[in] s the section
+ * \param[in] x the section count
+ */
 void ldns_pkt_set_section_count(ldns_pkt *p, ldns_pkt_section s, uint16_t x);
+/**
+ * Set the packet's tsig rr
+ * \param[in] p the packet
+ * \param[in] t the tsig rr
+ */
 void ldns_pkt_set_tsig(ldns_pkt *p, ldns_rr *t);
 
 /**
@@ -318,12 +491,48 @@ void ldns_pkt_set_tsig(ldns_pkt *p, ldns_rr *t);
  */
 ldns_pkt_type ldns_pkt_reply_type(ldns_pkt *p);
 
+/**
+ * return the packet's edns udp size
+ * \param[in] packet the packet
+ * \return the size
+ */
 uint16_t ldns_pkt_edns_udp_size(const ldns_pkt *packet);
+/**
+ * return the packet's edns extended rcode
+ * \param[in] packet the packet
+ * \return the rcode
+ */
 uint8_t ldns_pkt_edns_extended_rcode(const ldns_pkt *packet);
+/**
+ * return the packet's edns version
+ * \param[in] packet the packet
+ * \return the version
+ */
 uint8_t ldns_pkt_edns_version(const ldns_pkt *packet);
+/**
+ * return the packet's edns z value
+ * \param[in] packet the packet
+ * \return the z value
+ */
 uint16_t ldns_pkt_edns_z(const ldns_pkt *packet);
+/**
+ * return the packet's edns data
+ * \param[in] packet the packet
+ * \return the data
+ */
 ldns_rdf *ldns_pkt_edns_data(const ldns_pkt *packet);
+
+/**
+ * return the packet's edns do bit
+ * \param[in] packet the packet
+ * \return the bit's value
+ */
 bool ldns_pkt_edns_do(const ldns_pkt *packet);
+/**
+ * Set the packet's edns do bit
+ * \param[in] packet the packet
+ * \param[in] value the bit's new value
+ */
 void ldns_pkt_set_edns_do(ldns_pkt *packet, bool value);
 
 /**
@@ -336,10 +545,36 @@ void ldns_pkt_set_edns_do(ldns_pkt *packet, bool value);
  * \return true if packet needs edns rr
  */
 bool ldns_pkt_edns(const ldns_pkt *packet);
+
+/**
+ * Set the packet's edns udp size
+ * \param[in] packet the packet
+ * \param[in] s the size
+ */
 void ldns_pkt_set_edns_udp_size(ldns_pkt *packet, uint16_t s);
+/**
+ * Set the packet's edns extended rcode
+ * \param[in] packet the packet
+ * \param[in] c the code
+ */
 void ldns_pkt_set_edns_extended_rcode(ldns_pkt *packet, uint8_t c);
+/**
+ * Set the packet's edns version
+ * \param[in] packet the packet
+ * \param[in] v the version
+ */
 void ldns_pkt_set_edns_version(ldns_pkt *packet, uint8_t v);
+/**
+ * Set the packet's edns z value
+ * \param[in] packet the packet
+ * \param[in] z the value
+ */
 void ldns_pkt_set_edns_z(ldns_pkt *packet, uint16_t z);
+/**
+ * Set the packet's edns data
+ * \param[in] packet the packet
+ * \param[in] data the data
+ */
 void ldns_pkt_set_edns_data(ldns_pkt *packet, ldns_rdf *data);
 
 /**
@@ -411,10 +646,10 @@ void ldns_pkt_set_question(ldns_pkt *p, ldns_rr_list *rr);
  */
 void ldns_pkt_set_authority(ldns_pkt *p, ldns_rr_list *rr);
 
-/* lua helper stuff KEEP THIS?? NO YES */
+/* lua helper stuff KEEP THIS?? NO/YES */
+/**  TODO or remove */
 ldns_rr * ldns_pkt_get_rr(ldns_pkt *p, uint16_t n);
 ldns_rr * ldns_pkt_set_rr(ldns_pkt *p, ldns_rr *rr, uint16_t n);
 bool ldns_pkt_insert_rr(ldns_pkt *p, ldns_rr *rr, uint16_t n);
-	
 
 #endif  /* LDNS_PACKET_H */