more comments

2 files changed, 31 insertions, 2 deletions

diff --git a/milter_api.adb b/milter_api.adb
index 48316cc..f68b07a 100644
--- a/milter_api.adb
+++ b/milter_api.adb
@@ -855,6 +855,10 @@ package body Milter_API is
        Message       : Reply_Lines)
    is separate;
 
+
+   -- The functions Address and Port use the helper functions in
+   -- sockaddr_functions.c to extract data from sockaddr structures.
+
    milter_api_address_type_ipv4    : constant Unsigned_8 := 1;
    milter_api_address_type_ipv6    : constant Unsigned_8 := 2;
    milter_api_address_type_unknown : constant Unsigned_8 := 255;
diff --git a/sockaddr_functions.c b/sockaddr_functions.c
index 6148414..116253c 100644
--- a/sockaddr_functions.c
+++ b/sockaddr_functions.c
@@ -1,3 +1,16 @@
+// Ada Milter API, a binding to Libmilter, the Sendmail mail filtering API
+// Copyright 2012 - 2013 B. Persson, Bjorn@Rombobeorn.se
+//
+// This library is free software: you can redistribute it and/or modify it
+// under the terms of the GNU General Public License version 3, as published
+// by the Free Software Foundation.
+
+
+// This file contains helper functions for extracting address data from a
+// sockaddr, because trying to access the fields of sockaddr structures from
+// Ada in a portable way would get ugly fast.
+
+
 #include <stdint.h>
 #include <string.h>
 #include <sys/socket.h>
@@ -5,12 +18,16 @@
 #include <arpa/inet.h>
 
 
+// constants exported by milter_api.adb:
 extern const uint8_t milter_api_address_type_ipv4;
 extern const uint8_t milter_api_address_type_ipv6;
 extern const uint8_t milter_api_address_type_unknown;
 
 
-uint8_t milter_api_address_type(struct sockaddr const* const endpoint) {
+uint8_t milter_api_address_type(struct sockaddr const* const endpoint)
+// milter_api_address_type returns a code to tell which type of address
+// endpoint contains.
+{
    if(endpoint->sa_family == AF_INET) {
       return milter_api_address_type_ipv4;
    } else if(endpoint->sa_family == AF_INET6) {
@@ -23,6 +40,8 @@ uint8_t milter_api_address_type(struct sockaddr const* const endpoint) {
 
 void milter_api_ipv4_address(struct sockaddr_in const* const endpoint,  // in
                              uint8_t* const                  buffer)    // out
+// milter_api_ipv4_address copies the IPv4 address from endpoint to buffer.
+// buffer must be 4 bytes long.
 {
    memcpy(buffer, &endpoint->sin_addr, 4);
 }
@@ -30,6 +49,8 @@ void milter_api_ipv4_address(struct sockaddr_in const* const endpoint,  // in
 
 void milter_api_ipv6_address(struct sockaddr_in6 const* const endpoint,  // in
                              uint8_t* const                   buffer)    // out
+// milter_api_ipv6_address copies the IPv6 address from endpoint to buffer.
+// buffer must be 16 bytes long.
 {
    memcpy(buffer, &endpoint->sin6_addr, 16);
 }
@@ -38,6 +59,8 @@ void milter_api_ipv6_address(struct sockaddr_in6 const* const endpoint,  // in
 void milter_api_address_string(struct sockaddr const* const endpoint,  // in
                                char* const                  buffer,    // out
                                const uint8_t                size)      // in
+// milter_api_address_string writes in buffer a textual representation of the
+// IP address in endpoint. size is the length of buffer in bytes.
 {
    char const* result = NULL;
 
@@ -57,7 +80,9 @@ void milter_api_address_string(struct sockaddr const* const endpoint,  // in
 }
 
 
-uint16_t milter_api_port(struct sockaddr const* const endpoint) {
+uint16_t milter_api_port(struct sockaddr const* const endpoint)
+// milter_api_port returns (in host byte order) the port number in endpoint.
+{
    if(endpoint->sa_family == AF_INET) {
       return ntohs(((struct sockaddr_in const*)endpoint)->sin_port);
    } else if(endpoint->sa_family == AF_INET6) {