diff --git a/src/vnet/bfd/bfd_api.c b/src/vnet/bfd/bfd_api.c
index e64df48..185c03c 100644
--- a/src/vnet/bfd/bfd_api.c
+++ b/src/vnet/bfd/bfd_api.c
@@ -16,6 +16,10 @@
  * limitations under the License.
  *------------------------------------------------------------------
  */
+/**
+ * @file
+ * @brief BFD binary API implementation
+ */
 
 #include <vnet/vnet.h>
 #include <vlibmemory/api.h>
diff --git a/src/vnet/bfd/bfd_api.h b/src/vnet/bfd/bfd_api.h
index 35ad3cd..9f0509d 100644
--- a/src/vnet/bfd/bfd_api.h
+++ b/src/vnet/bfd/bfd_api.h
@@ -14,7 +14,7 @@
  */
 /**
  * @file
- * @brief BFD global declarations
+ * @brief BFD API declarations
  */
 #ifndef __included_bfd_api_h__
 #define __included_bfd_api_h__
@@ -34,6 +34,9 @@
 #undef F
 } bfd_transport_e;
 
+/**
+ * @brief create a new bfd session
+ */
 vnet_api_error_t
 bfd_udp_add_session (u32 sw_if_index, const ip46_address_t * local_addr,
 		     const ip46_address_t * peer_addr,
@@ -41,39 +44,66 @@
 		     u8 detect_mult, u8 is_authenticated, u32 conf_key_id,
 		     u8 bfd_key_id);
 
+/**
+ * @brief modify existing session
+ */
 vnet_api_error_t
 bfd_udp_mod_session (u32 sw_if_index, const ip46_address_t * local_addr,
 		     const ip46_address_t * peer_addr,
 		     u32 desired_min_tx_usec, u32 required_min_rx_usec,
 		     u8 detect_mult);
 
+/**
+ * @brief delete existing session
+ */
 vnet_api_error_t bfd_udp_del_session (u32 sw_if_index,
 				      const ip46_address_t * local_addr,
 				      const ip46_address_t * peer_addr);
 
+/**
+ * @brief set session admin down/up
+ */
 vnet_api_error_t bfd_udp_session_set_flags (u32 sw_if_index,
 					    const ip46_address_t * local_addr,
 					    const ip46_address_t * peer_addr,
 					    u8 admin_up_down);
 
+/**
+ * @brief create or modify bfd authentication key
+ */
 vnet_api_error_t bfd_auth_set_key (u32 conf_key_id, u8 auth_type, u8 key_len,
 				   const u8 * key);
 
+/**
+ * @brief delete existing authentication key
+ */
 vnet_api_error_t bfd_auth_del_key (u32 conf_key_id);
 
+/**
+ * @brief activate authentication for existing session
+ */
 vnet_api_error_t bfd_udp_auth_activate (u32 sw_if_index,
 					const ip46_address_t * local_addr,
 					const ip46_address_t * peer_addr,
 					u32 conf_key_id, u8 bfd_key_id,
 					u8 is_delayed);
 
+/**
+ * @brief deactivate authentication for existing session
+ */
 vnet_api_error_t bfd_udp_auth_deactivate (u32 sw_if_index,
 					  const ip46_address_t * local_addr,
 					  const ip46_address_t * peer_addr,
 					  u8 is_delayed);
 
+/**
+ * @brief set echo-source interface
+ */
 vnet_api_error_t bfd_udp_set_echo_source (u32 loopback_sw_if_index);
 
+/**
+ * @brief unset echo-source interface
+ */
 vnet_api_error_t bfd_udp_del_echo_source ();
 
 #endif /* __included_bfd_api_h__ */
diff --git a/src/vnet/bfd/bfd_cli.c b/src/vnet/bfd/bfd_cli.c
index a3736d9..f15acb4 100644
--- a/src/vnet/bfd/bfd_cli.c
+++ b/src/vnet/bfd/bfd_cli.c
@@ -737,7 +737,7 @@
                 " peer-addr <peer-address>"
                 " conf-key-id <config key ID>"
                 " bfd-key-id <BFD key ID>"
-                " [ delayed <yes|no>]",
+                " [ delayed <yes|no> ]",
   .function = bfd_cli_udp_session_auth_activate,
 };
 
@@ -815,7 +815,7 @@
                 " interface <interface>"
                 " local-addr <local-address>"
                 " peer-addr <peer-address>"
-                "[ delayed <yes|no>]",
+                "[ delayed <yes|no> ]",
   .function = bfd_cli_udp_session_auth_deactivate,
 };
 /* *INDENT-ON* */
diff --git a/src/vnet/bfd/bfd_doc.md b/src/vnet/bfd/bfd_doc.md
index 3e86b17..7d7606e 100644
--- a/src/vnet/bfd/bfd_doc.md
+++ b/src/vnet/bfd/bfd_doc.md
@@ -1,3 +1,374 @@
-# BFD Notes    {#bfd_doc}
+# BFD module    {#bfd_doc}
 
-@todo Someone needs to produce this or remove the stub file.
+## Overview
+
+Bidirectional Forwarding Detection in VPP currently supports single-hop UDP
+transport based on RFC 5880 and RFC 5881.
+
+## Usage
+
+### General usage
+
+BFD sessions are created using APIs only. The following CLIs are implemented,
+which call the APIs to manipulate the BFD:
+
+#### Show commands:
+
+> show bfd [keys|sessions|echo-source]
+
+Show the existing keys, sessions or echo-source.
+
+#### Key manipulation
+
+##### Create a new key or modify an existing key
+
+> bfd key set conf-key-id <id> type <keyed-sha1|meticulous-keyed-sha1> secret <secret>
+
+Parameters:
+
+* conf-key-id     - local configuration key ID, used to uniquely identify this key
+* type            - type of the key
+* secret          - shared secret (hex data)
+
+Example:
+
+> bfd key set conf-key-id 2368880803 type meticulous-keyed-sha1 secret 69d685b0d990cdba46872706dc
+
+Notes:
+
+* in-use key cannot be modified
+
+##### Delete an existing key
+
+> bfd key del conf-key-id <id>
+
+Parameters:
+
+* conf-key-id     - local configuration key ID, used to uniquely identify this key
+
+Example:
+
+> bfd key del conf-key-id 2368880803
+
+Notes:
+
+*  in-use key cannot be deleted
+
+##### Create a new (plain or authenticated) BFD session
+
+> bfd udp session add interface <interface> local-addr <address> peer-addr <address> desired-min-tx <interval> required-min-rx <interval> detect-mult <multiplier> [ conf-key-id <ID> bfd-key-id <ID> ]
+
+Parameters:
+
+* interface       - interface to which this session is tied to
+* local-addr      - local address (ipv4 or ipv6)
+* peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)
+* desired-min-tx  - desired minimum tx interval (microseconds)
+* required-min-rx - required minimum rx interval (microseconds)
+* detect-mult     - detect multiplier (must be non-zero)
+* conf-key-id     - local configuration key ID
+* bfd-key-id      - BFD key ID, as carried in BFD control frames
+
+Example:
+
+> bfd udp session add interface pg0 local-addr fd01:1::1 peer-addr fd01:1::2 desired-min-tx 100000 required-min-rx 100000 detect-mult 3 conf-key-id 1029559112 bfd-key-id 13
+
+Notes:
+
+* if conf-key-id and bfd-key-id are not specified, session is non-authenticated
+* desired-min-tx controls desired transmission rate of both control frames and echo packets
+
+##### Modify BFD session
+
+> bfd udp session mod interface <interface> local-addr <address> peer-addr <address> desired-min-tx <interval> required-min-rx <interval> detect-mult <multiplier>
+
+Parameters:
+
+* interface       - interface to which this session is tied to
+* local-addr      - local address (ipv4 or ipv6)
+* peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)
+* desired-min-tx  - desired minimum tx interval (microseconds)
+* required-min-rx - required minimum rx interval (microseconds)
+* detect-mult     - detect multiplier (must be non-zero)
+
+Example:
+
+> bfd udp session mod interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2 desired-min-tx 300000 required-min-rx 200000 detect-mult 12
+
+Notes:
+
+* desired-min-tx controls desired transmission rate of both control frames and echo packets
+
+##### Delete an existing BFD session
+
+> bfd udp session del interface <interface> local-addr <address> peer-addr<address>
+
+Parameters:
+
+* interface       - interface to which this session is tied to
+* local-addr      - local address (ipv4 or ipv6)
+* peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)
+
+Example:
+
+> bfd udp session del interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2
+
+##### Set session admin-up or admin-down
+
+> bfd udp session set-flags interface <interface> local-addr <address> peer-addr <address> admin <up|down>
+
+Parameters:
+
+* interface       - interface to which this session is tied to
+* local-addr      - local address (ipv4 or ipv6)
+* peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)
+* admin           - up/down based on desired action
+
+Example:
+
+> bfd udp session set-flags admin down interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2
+
+##### Activate/change authentication for existing session
+
+> bfd udp session auth activate interface <interface> local-addr <address> peer-addr <address> conf-key-id <ID> bfd-key-id <ID> [ delayed <yes|no> ]
+
+Parameters:
+
+* interface       - interface to which this session is tied to
+* local-addr      - local address (ipv4 or ipv6)
+* peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)
+* conf-key-id     - local configuration key ID
+* bfd-key-id      - BFD key ID, as carried in BFD control frames
+* delayed         - is yes then this action is delayed until the peer performs the same action
+
+Example:
+
+> bfd udp session auth activate interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2 conf-key-id 540928695 bfd-key-id 239 delayed yes
+
+Notes:
+
+* see [Delayed option] for more information
+
+##### Deactivate authentication for existing session
+
+> bfd udp session auth deactivate interface <interface> local-addr <address> peer-addr <address> [ delayed <yes|no> ]
+
+Parameters:
+
+* interface       - interface to which this session is tied to
+* local-addr      - local address (ipv4 or ipv6)
+* peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)
+* delayed         - is yes then this action is delayed until the peer performs the same action
+
+Example:
+
+> bfd udp session auth deactivate interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2
+
+Notes:
+
+* see [Delayed option] for more information
+
+##### Set echo-source interface
+
+> bfd udp echo-source set interface <interface>
+
+Parameters:
+
+* interface       - interface used for getting source address for echo packets
+
+Example:
+
+> bfd udp echo-source set interface loop0
+
+##### Delete echo-source interface
+
+> bfd udp echo-source del
+
+Example:
+
+> bfd udp echo-source del
+
+### Authentication
+
+BFD sessions should be authenticated for security purposes. SHA1 and meticulous
+SHA1 authentication is supported by VPP. First, authentication keys are
+configured in VPP and afterwards they can be used by sessions.
+
+There are two key IDs in the scope of BFD session:
+
+* configuration key ID is the internal unique key ID inside VPP and is never
+  communicated to any peer, it serves only the purpose of identifying the key
+* BFD key ID is the key ID carried in BFD control frames and is used for
+  verifying authentication
+
+#### Turning auth on/off
+
+Authentication can be turned on or off at any time. Care must be taken however,
+to either synchronize the authentication manipulation with peer's actions
+to avoid the session going down.
+
+##### Delayed option
+
+Delayed option is useful for synchronizing authentication changes with a peer.
+If it's specified, then authentication change is not performed immediately.
+In this case, VPP continues to transmit packets using the old authentication
+method (unauthenticated or using old sha1 key). If a packet is received, which
+does not pass the current authentication, then VPP tries to authenticate it
+using the new method (which might be none, if deactivating authentication)
+and if it passes, then the new authentication method is put in use.
+
+The recommended procedure for enabling/changing/disabling session 
+authentication is:
+
+1. perform authentication change on vpp's side with delayed option set to yes
+2. perform authentication change on peer's side (without delayed option)
+
+Notes:
+
+* if both peers use delayed option at the same time, the change will never
+  be carried out, since none of the peers will see any packet with the new
+  authentication which could trigger the change
+* remote peer does not need to support or even be aware of this mechanism
+  for it to work properly
+
+
+### Echo function
+
+Echo function is used by VPP whenever a peer declares the willingness
+to support it, echo-source is set and it contains a usable subnet (see below).
+When echo function is switched on, the required min rx interval advertised
+to peer is set to 1 second (or the configured value, if its higher).
+
+#### Echo source address
+
+Because echo packets are only looped back (and not processed in any way)
+by a peer, it's necessary to set the source address in a way which avoids
+packet drop due to spoofing protection by VPP. Per RFC, the source address
+should not be in the subnet set on the interface over which the echo packets
+are sent. Also, it must not be any VPP-local address, otherwise the packet
+gets dropped on receipt by VPP. The solution is to create a loopback interface
+with a (private) IPv4/IPv6 subnet assigned as echo-source. The BFD then picks
+an unused address from the subnet by flipping the last bit and uses that as
+source address in the echo packets, thus meeting RFC recommendation while
+avoiding spoofing protection.
+
+Example: if 10.10.10.3/31 is the subnet, then 10.10.10.2 will be used as
+         source address in (IPv4) echo packets
+
+### Demand mode
+
+Demand mode is respected by VPP, but not used locally. The only scenario when
+demand mode could make sense currently is when echo is active. Because echo
+packets are inherently insecure against an adversary looping them back a poll
+sequence would be required for slow periodic connectivity verification anyway.
+It's more efficient to just ask the remote peer to send slow periodic control
+frames without VPP initiating periodic poll sequences.
+
+### Admin-down
+
+Session may be put admin-down at any time. This immediately causes the state
+to be changed to AdminDown and remain so unless the session is put admin-up.
+
+## BFD implementation notes
+
+Because BFD can work over different transport layers, the BFD code is separated
+into core BFD functionality - main module implemented in bfd_main.c
+and transport-specific code implemented in bfd_udp.c.
+
+### Main module
+
+Main module is responsible for handling all the BFD functionality defined
+in RFC 5880.
+
+#### Internal API
+
+Internal APIs defined in bfd_main.h are called from transport-specific code
+to create/modify/delete
+
+#### Packet receipt
+
+When a packet is received by the transport layer, it is forwarded to main
+module (to main thread) via an RPC call. At this point, the authentication has
+been verified, so the packet is consumed, session parameters are updated
+accordingly and state change (if applicable). Based on these, the timeouts
+are adjusted if required and an event is sent to the process node to wake up
+and recalculate sleep time.
+
+#### Packet transmit
+
+Main module allocates a vlib_buffer_t, creates the required BFD frame (control
+or echo in it), then calls the transport layer to add the transport layer.
+Then a frame containing the buffer to the aprropriate node is created
+and enqueued.
+
+#### Process node
+
+Main module implements one process node which is a simple loop. The process
+node gets next timeout from the timer wheel, sleeps until the timeout expires
+and then calls a timeout routine which drives the state machine for each
+session which timed out. The sleep is interrupted externally via vlib event,
+when a session is added or modified in a way which might require timer wheel
+manipulation. In this case the caller inserts the necessary timeout to timer
+wheel and then signals the process node to wake up early, handle possible
+timeouts and recalculate the sleep time again.
+
+#### State machine
+
+Default state of BFD session when created is Down, per RFC 5880. State changes
+to Init, Up or Down based on events like received state from peer and timeouts.
+The session state can be set AdminDown using a binary API, which prevents it
+from going to any other state, until this limitation is removed. This state
+is advertised to peers in slow periodic control frames.
+
+For each session, the following timeouts are maintained:
+
+1. tx timeout - used for sending out control frames
+2. rx timeout - used for detecting session timeout
+3. echo tx timeout - used for sending out echo frames
+3. echo rx timeout - used for detecting session timeout based on echo
+
+These timeouts are maintained in cpu clocks and recalculated when appropriate
+(e.g. rx timeout is bumped when a packet is received, keeping the session
+alive). Only the earliest timeout is inserted into the timer wheel at a time
+and timer wheel events are never deleted, rather spurious events are ignored.
+This allows efficient operation, like not inserting events into timing wheel
+for each packet received or ignoring left-over events in case a bfd session
+gets removed and a new one is recreated with the same session index.
+
+#### Authentication keys management
+
+Authentication keys are managed internally in a pool, with each key tracking
+it's use count. The removal/modification is only allowed if the key is not in
+use.
+
+### UDP module
+
+UDP module is responsible for:
+
+1. public APIs/CLIs to configure BFD over UDP.
+2. support code called by main module to encapsulate/decapsulate BFD packets
+
+This module implements two graph nodes - for consuming ipv4 and ipv6 packets
+target at BFD ports 3874 and 3875.
+
+#### Packet receipt
+
+BFD packet receipt receipt starts in the bfd udp graph nodes. Since the code
+needs to verify IP/UDP header data, it relies on ip4-local (and ip6-local)
+nodes to store pointers to the appropriate headers. First, your discriminator
+is extracted from BFD packet and used to lookup the existing session. In case
+it's zero, the pair of IP addresses and sw_if_index is used to lookup session.
+Then, main module is called to verify the authentication, if present.
+Afterwards a check is made if the IP/UDP headers are correct. If yes, then
+an RPC call is made to the main thread to consume the packet and take action
+upon it.
+
+#### Packet transmission
+
+When process node decides that there is a need to transmit the packet, it
+creates a buffer, fills the BFD frame data in and calls the UDP module to
+add the transport layer. This is a simple operation for the control frames
+consisting of just adding UDP/IP headers based on session data. For echo
+frames, an additional step, looking at the echo-source interface and picking
+and address is performed and if this fails, then the packet cannot be
+transmitted and an error is returned to main thread.
diff --git a/src/vnet/bfd/bfd_main.c b/src/vnet/bfd/bfd_main.c
index d38623c..ea6db1f 100644
--- a/src/vnet/bfd/bfd_main.c
+++ b/src/vnet/bfd/bfd_main.c
@@ -1606,8 +1606,6 @@
   bfd_set_remote_required_min_echo_rx (bm, bs, now,
 				       clib_net_to_host_u32
 				       (pkt->req_min_echo_rx));
-  /* FIXME 6.8.2 */
-  /* FIXME 6.8.4 */
   if (bfd_pkt_get_final (pkt))
     {
       if (BFD_POLL_IN_PROGRESS == bs->poll_state)
@@ -1915,13 +1913,13 @@
 {
 #if WITH_LIBSSL > 0
   bfd_auth_key_t *auth_key = NULL;
-  if (!key_len || key_len > bfd_max_len_for_auth_type (auth_type))
+  if (!key_len || key_len > bfd_max_key_len_for_auth_type (auth_type))
     {
       clib_warning ("Invalid authentication key length for auth_type=%d:%s "
 		    "(key_len=%u, must be "
 		    "non-zero, expected max=%u)",
 		    auth_type, bfd_auth_type_str (auth_type), key_len,
-		    (u32) bfd_max_len_for_auth_type (auth_type));
+		    (u32) bfd_max_key_len_for_auth_type (auth_type));
       return VNET_API_ERROR_INVALID_VALUE;
     }
   if (!bfd_auth_type_supported (auth_type))
diff --git a/src/vnet/bfd/bfd_main.h b/src/vnet/bfd/bfd_main.h
index 3be3694..4d460f4 100644
--- a/src/vnet/bfd/bfd_main.h
+++ b/src/vnet/bfd/bfd_main.h
@@ -37,19 +37,19 @@
 
 typedef struct
 {
-  /* global configuration key ID */
+  /** global configuration key ID */
   u32 conf_key_id;
 
-  /* keeps track of how many sessions reference this key */
+  /** keeps track of how many sessions reference this key */
   u32 use_count;
 
-  /*
+  /**
    * key data directly usable for bfd purposes - already padded with zeroes
    * (so we don't need the actual length)
    */
   u8 key[20];
 
-  /* authentication type for this key */
+  /** authentication type for this key */
   bfd_auth_type_e auth_type;
 } bfd_auth_key_t;
 
@@ -68,152 +68,152 @@
 
 typedef struct bfd_session_s
 {
-  /* index in bfd_main.sessions pool */
+  /** index in bfd_main.sessions pool */
   u32 bs_idx;
 
-  /* session state */
+  /** session state */
   bfd_state_e local_state;
 
-  /* remote session state */
+  /** remote session state */
   bfd_state_e remote_state;
 
-  /* local diagnostics */
+  /** local diagnostics */
   bfd_diag_code_e local_diag;
 
-  /* remote diagnostics */
+  /** remote diagnostics */
   bfd_diag_code_e remote_diag;
 
-  /* local discriminator */
+  /** local discriminator */
   u32 local_discr;
 
-  /* remote discriminator */
+  /** remote discriminator */
   u32 remote_discr;
 
-  /* configured desired min tx interval (microseconds) */
+  /** configured desired min tx interval (microseconds) */
   u32 config_desired_min_tx_usec;
 
-  /* configured desired min tx interval (clocks) */
+  /** configured desired min tx interval (clocks) */
   u64 config_desired_min_tx_clocks;
 
-  /* effective desired min tx interval (clocks) */
+  /** effective desired min tx interval (clocks) */
   u64 effective_desired_min_tx_clocks;
 
-  /* configured required min rx interval (microseconds) */
+  /** configured required min rx interval (microseconds) */
   u32 config_required_min_rx_usec;
 
-  /* configured required min rx interval (clocks) */
+  /** configured required min rx interval (clocks) */
   u64 config_required_min_rx_clocks;
 
-  /* effective required min rx interval (clocks) */
+  /** effective required min rx interval (clocks) */
   u64 effective_required_min_rx_clocks;
 
-  /* remote min rx interval (microseconds) */
+  /** remote min rx interval (microseconds) */
   u64 remote_min_rx_usec;
 
-  /* remote min rx interval (clocks) */
+  /** remote min rx interval (clocks) */
   u64 remote_min_rx_clocks;
 
-  /* remote min echo rx interval (microseconds) */
+  /** remote min echo rx interval (microseconds) */
   u64 remote_min_echo_rx_usec;
 
-  /* remote min echo rx interval (clocks) */
+  /** remote min echo rx interval (clocks) */
   u64 remote_min_echo_rx_clocks;
 
-  /* remote desired min tx interval (clocks) */
+  /** remote desired min tx interval (clocks) */
   u64 remote_desired_min_tx_clocks;
 
-  /* configured detect multiplier */
+  /** configured detect multiplier */
   u8 local_detect_mult;
 
-  /* 1 if remote system sets demand mode, 0 otherwise */
+  /** 1 if remote system sets demand mode, 0 otherwise */
   u8 remote_demand;
 
-  /* remote detect multiplier */
+  /** remote detect multiplier */
   u8 remote_detect_mult;
 
-  /* 1 is echo function is active, 0 otherwise */
+  /** 1 is echo function is active, 0 otherwise */
   u8 echo;
 
-  /* set to value of timer in timing wheel, 0 if never set */
+  /** set to value of timer in timing wheel, 0 if never set */
   u64 wheel_time_clocks;
 
-  /* transmit interval */
+  /** transmit interval */
   u64 transmit_interval_clocks;
 
-  /* next time at which to transmit a packet */
+  /** next time at which to transmit a packet */
   u64 tx_timeout_clocks;
 
-  /* timestamp of last packet transmitted */
+  /** timestamp of last packet transmitted */
   u64 last_tx_clocks;
 
-  /* timestamp of last packet received */
+  /** timestamp of last packet received */
   u64 last_rx_clocks;
 
-  /* transmit interval for echo packets */
+  /** transmit interval for echo packets */
   u64 echo_transmit_interval_clocks;
 
-  /* next time at which to transmit echo packet */
+  /** next time at which to transmit echo packet */
   u64 echo_tx_timeout_clocks;
 
-  /* timestamp of last echo packet transmitted */
+  /** timestamp of last echo packet transmitted */
   u64 echo_last_tx_clocks;
 
-  /* timestamp of last echo packet received */
+  /** timestamp of last echo packet received */
   u64 echo_last_rx_clocks;
 
-  /* secret used for calculating/checking checksum of echo packets */
+  /** secret used for calculating/checking checksum of echo packets */
   u32 echo_secret;
 
-  /* detection time */
+  /** detection time */
   u64 detection_time_clocks;
 
-  /* state info regarding poll sequence */
+  /** state info regarding poll sequence */
   bfd_poll_state_e poll_state;
 
-  /*
+  /**
    * helper for delayed poll sequence - marks either start of running poll
    * sequence or timeout, after which we can start the next poll sequnce
    */
   u64 poll_state_start_or_timeout_clocks;
 
-  /* authentication information */
+  /** authentication information */
   struct
   {
-    /* current key in use */
+    /** current key in use */
     bfd_auth_key_t *curr_key;
 
-    /*
+    /**
      * set to next key to use if delayed switch is enabled - in that case
      * the key is switched when first incoming packet is signed with next_key
      */
     bfd_auth_key_t *next_key;
 
-    /* sequence number incremented occasionally or always (if meticulous) */
+    /** sequence number incremented occasionally or always (if meticulous) */
     u32 local_seq_number;
 
-    /* remote sequence number */
+    /** remote sequence number */
     u32 remote_seq_number;
 
-    /* set to 1 if remote sequence number is known */
+    /** set to 1 if remote sequence number is known */
     u8 remote_seq_number_known;
 
-    /* current key ID sent out in bfd packet */
+    /** current key ID sent out in bfd packet */
     u8 curr_bfd_key_id;
 
-    /* key ID to use when switched to next_key */
+    /** key ID to use when switched to next_key */
     u8 next_bfd_key_id;
 
-    /*
+    /**
      * set to 1 if delayed action is pending, which might be activation
      * of authentication, change of key or deactivation
      */
     u8 is_delayed;
   } auth;
 
-  /* transport type for this session */
+  /** transport type for this session */
   bfd_transport_e transport;
 
-  /* union of transport-specific data */
+  /** union of transport-specific data */
   union
   {
     bfd_udp_session_t udp;
@@ -222,48 +222,48 @@
 
 typedef struct
 {
-  /* pool of bfd sessions context data */
+  /** pool of bfd sessions context data */
   bfd_session_t *sessions;
 
-  /* timing wheel for scheduling timeouts */
+  /** timing wheel for scheduling timeouts */
   timing_wheel_t wheel;
 
-  /* timing wheel inaccuracy, in clocks */
+  /** timing wheel inaccuracy, in clocks */
   u64 wheel_inaccuracy;
 
-  /* hashmap - bfd session by discriminator */
+  /** hashmap - bfd session by discriminator */
   u32 *session_by_disc;
 
-  /* background process node index */
+  /** background process node index */
   u32 bfd_process_node_index;
 
-  /* convenience variables */
+  /** convenience variables */
   vlib_main_t *vlib_main;
   vnet_main_t *vnet_main;
 
-  /* cpu clocks per second */
+  /** cpu clocks per second */
   f64 cpu_cps;
 
-  /* default desired min tx in clocks */
+  /** default desired min tx in clocks */
   u64 default_desired_min_tx_clocks;
 
-  /* minimum required min rx while echo function is active - clocks */
+  /** minimum required min rx while echo function is active - clocks */
   u64 min_required_min_rx_while_echo_clocks;
 
-  /* for generating random numbers */
+  /** for generating random numbers */
   u32 random_seed;
 
-  /* pool of authentication keys */
+  /** pool of authentication keys */
   bfd_auth_key_t *auth_keys;
 
-  /* hashmap - index in pool auth_keys by conf_key_id */
+  /** hashmap - index in pool auth_keys by conf_key_id */
   u32 *auth_key_by_conf_key_id;
 
 } bfd_main_t;
 
 extern bfd_main_t bfd_main;
 
-/* Packet counters */
+/** Packet counters */
 #define foreach_bfd_error(F)               \
   F (NONE, "good bfd packets (processed)") \
   F (BAD, "invalid bfd packets")           \
@@ -277,7 +277,7 @@
     BFD_N_ERROR,
 } bfd_error_t;
 
-/* bfd packet trace capture */
+/** bfd packet trace capture */
 typedef struct
 {
   u32 len;
@@ -291,14 +291,14 @@
   BFD_EVENT_CONFIG_CHANGED,
 } bfd_process_event_e;
 
-/* echo packet structure */
 /* *INDENT-OFF* */
+/** echo packet structure */
 typedef CLIB_PACKED (struct {
-  /* local discriminator */
+  /** local discriminator */
   u32 discriminator;
-  /* expire time of this packet - clocks */
+  /** expire time of this packet - clocks */
   u64 expire_time_clocks;
-  /* checksum - based on discriminator, local secret and expire time */
+  /** checksum - based on discriminator, local secret and expire time */
   u64 checksum;
 }) bfd_echo_pkt_t;
 /* *INDENT-ON* */
@@ -335,10 +335,10 @@
 #define USEC_PER_MS 1000LL
 #define USEC_PER_SECOND (1000 * USEC_PER_MS)
 
-/* default, slow transmission interval for BFD packets, per spec at least 1s */
+/** default, slow transmission interval for BFD packets, per spec at least 1s */
 #define BFD_DEFAULT_DESIRED_MIN_TX_USEC USEC_PER_SECOND
 
-/*
+/**
  * minimum required min rx set locally when echo function is used, per spec
  * should be set to at least 1s
  */
diff --git a/src/vnet/bfd/bfd_protocol.c b/src/vnet/bfd/bfd_protocol.c
index 5deb970..cd51e91 100644
--- a/src/vnet/bfd/bfd_protocol.c
+++ b/src/vnet/bfd/bfd_protocol.c
@@ -12,6 +12,10 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * @file
+ * @brief BFD protocol implementation
+ */
 #include <vnet/bfd/bfd_protocol.h>
 
 u8
@@ -131,7 +135,7 @@
 #endif
 
 u32
-bfd_max_len_for_auth_type (bfd_auth_type_e auth_type)
+bfd_max_key_len_for_auth_type (bfd_auth_type_e auth_type)
 {
 #define F(t, l, n, s) \
   if (auth_type == t) \
diff --git a/src/vnet/bfd/bfd_protocol.h b/src/vnet/bfd/bfd_protocol.h
index cdbb8fa..210c561 100644
--- a/src/vnet/bfd/bfd_protocol.h
+++ b/src/vnet/bfd/bfd_protocol.h
@@ -40,7 +40,10 @@
 #undef F
 } bfd_auth_type_e;
 
-u32 bfd_max_len_for_auth_type (bfd_auth_type_e auth_type);
+/**
+ * @brief get the maximum length of key data for given auth type
+ */
+u32 bfd_max_key_len_for_auth_type (bfd_auth_type_e auth_type);
 const char *bfd_auth_type_str (bfd_auth_type_e auth_type);
 
 /* *INDENT-OFF* */
diff --git a/src/vnet/bfd/bfd_udp.c b/src/vnet/bfd/bfd_udp.c
index e6dbaab..b3eabc9 100644
--- a/src/vnet/bfd/bfd_udp.c
+++ b/src/vnet/bfd/bfd_udp.c
@@ -12,6 +12,10 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * @file
+ * @brief BFD UDP transport layer implementation
+ */
 #include <vppinfra/types.h>
 #include <vlibmemory/api.h>
 #include <vlib/vlib.h>
diff --git a/src/vnet/bfd/bfd_udp.h b/src/vnet/bfd/bfd_udp.h
index e33b740..5080ec9 100644
--- a/src/vnet/bfd/bfd_udp.h
+++ b/src/vnet/bfd/bfd_udp.h
@@ -13,7 +13,7 @@
  */
 /**
  * @file
- * @brief BFD global declarations
+ * @brief BFD UDP transport layer declarations
  */
 
 #ifndef __included_bfd_udp_h__
@@ -25,23 +25,27 @@
 #include <vnet/bfd/bfd_api.h>
 
 /* *INDENT-OFF* */
+/** identifier of BFD session based on UDP transport only */
 typedef CLIB_PACKED (struct {
-
+  /** interface to which the session is tied */
   u32 sw_if_index;
+  /** local address */
   ip46_address_t local_addr;
+  /** peer address */
   ip46_address_t peer_addr;
-
 }) bfd_udp_key_t;
 /* *INDENT-ON* */
 
+/** UDP transport specific data embedded in bfd_session's union */
 typedef struct
 {
+  /** key identifying this session */
   bfd_udp_key_t key;
-
+  /** adjacency index returned from adj lock call */
   adj_index_t adj_index;
 } bfd_udp_session_t;
 
-/* bfd udp echo packet trace capture */
+/** bfd udp echo packet trace capture */
 typedef struct
 {
   u32 len;
@@ -50,8 +54,23 @@
 
 struct bfd_session_s;
 
+/**
+ * @brief add the necessary transport layer by prepending it to existing data
+ *
+ * @param is_echo 1 if this is echo packet, 0 if control frame
+ *
+ * @return 1 on success, 0 on failure
+ */
 int bfd_add_udp4_transport (vlib_main_t * vm, vlib_buffer_t * b,
 			    const struct bfd_session_s *bs, int is_echo);
+
+/**
+ * @brief add the necessary transport layer by prepending it to existing data
+ *
+ * @param is_echo 1 if this is echo packet, 0 if control frame
+ *
+ * @return 1 on success, 0 on failure
+ */
 int bfd_add_udp6_transport (vlib_main_t * vm, vlib_buffer_t * b,
 			    const struct bfd_session_s *bs, int is_echo);
 
@@ -62,10 +81,12 @@
  */
 int bfd_udp_is_echo_available (bfd_transport_e transport);
 
-void
-bfd_udp_get_echo_source (int *is_set, u32 * sw_if_index, int *have_usable_ip4,
-			 ip4_address_t * ip4, int *have_usable_ip6,
-			 ip6_address_t * ip6);
+/**
+ * @brief get echo source information - used by CLI
+ */
+void bfd_udp_get_echo_source (int *is_set, u32 * sw_if_index,
+			      int *have_usable_ip4, ip4_address_t * ip4,
+			      int *have_usable_ip6, ip6_address_t * ip6);
 
 #endif /* __included_bfd_udp_h__ */
 
diff --git a/src/vnet/bfd/dir.dox b/src/vnet/bfd/dir.dox
index ed656b5..b9a5978 100644
--- a/src/vnet/bfd/dir.dox
+++ b/src/vnet/bfd/dir.dox
@@ -13,6 +13,6 @@
  * limitations under the License.
  */
 /**
- @dir vnet/vnet/bfd
+ @dir
  @brief Bidirectional Forwarding Detection (BFD) implementation
 */