Update some docs and specs and resolve some documentation TODOs

src/riak_core_coverage_filter.erl

@@ -1,7 +1,7 @@
-
+%% -------------------------------------------------------------------
 %%
-%% riak_core_coverage_filter: Manage results for a bucket from a
-%%                    coverage operation including any necessary filtering.
+%% riak_core_coverage_filter: Construct coverage filter functions.
+%%                        
 %%
 %% Copyright (c) 2007-2011 Basho Technologies, Inc.  All Rights Reserved.
 %%
@@ -21,18 +21,30 @@
 %%
 %% -------------------------------------------------------------------
 
+%% @doc This module is used to construct a property list of VNode
+%%      indexes and a functions to filter results from a coverage
+%%      operation. This may include filtering based on the particular
+%%      VNode or filtering on each item in the result list from any
+%%      VNode.
+
 -module(riak_core_coverage_filter).
 -author('Kelly McLaughlin <kelly@basho.com>').
 
 %% API
 -export([build_filters/4]).
 
+-type bucket() :: binary().
+-type filter() :: none | fun().
+-type filter_list() :: [{index(), fun()}].
+-type index() :: non_neg_integer().
+-type vnodes() :: [{index(), node()}].
 
 %% ===================================================================
 %% Public API
 %% ===================================================================
 
-%% @doc TODO
+%% @doc Build the list of filter functions for any required VNode indexes.
+-spec build_filters(bucket(), filter(), vnodes(), [index()]) -> filter_list().
 build_filters(Bucket, FilterInput, VNodes, FilterVNodes) ->
     ItemFilter = build_item_filter(FilterInput),
 
@@ -114,10 +126,6 @@ build_item_filter(FilterInput) ->
 
 %% @private
 build_preflist_fun(Bucket, Ring) ->
-    %% TODO: Change this to use the upcoming addition to
-    %% riak_core_ring that will allow finding the index
-    %% responsible for a bkey pair without working out the
-    %% entire preflist.
     fun(Key) ->
             riak_core_ring:responsible_index({Bucket, Key}, Ring)
     end.

src/riak_core_coverage_fsm.erl

@@ -1,6 +1,7 @@
 %% -------------------------------------------------------------------
 %%
-%% riak_core_coverage_fsm: TODO
+%% riak_core_coverage_fsm: Distribute work to a covering set of VNodes.
+%% 
 %%
 %% Copyright (c) 2007-2011 Basho Technologies, Inc.  All Rights Reserved.
 %%
@@ -20,19 +21,31 @@
 %%
 %% -------------------------------------------------------------------
 
-%% @doc TODO
+%% @doc The coverage fsm is a behavior used to create
+%%      a plan to cover a set of VNodes, distribute
+%%      a specified command to each VNode in the plan
+%%      and then compile the results.
 %%
-%%      The keys fsm creates a plan to achieve coverage
-%%      of all keys from the cluster using the minimum
-%%      possible number of VNodes, sends key listing
-%%      commands to each of those VNodes, and compiles the
-%%      responses.
+%%      The number of VNodes required for full coverage
+%%      is based on the number of partitions, the bucket
+%%      n_val, and the number of primary VNodes from the
+%%      preference list that are configured to be used by
+%%      the module implementing this behavior.
 %%
-%%      The number of VNodes required for full
-%%      coverage is based on the number
-%%      of partitions, the number of available physical
-%%      nodes, and the bucket n_val.
-
+%%      Modules implementing this behavior should return 
+%%      a 5 member tuple from their init function that looks
+%%      like this: 
+%%          {ok, ModFun, PrimaryVNodeCoverage, 
+%%            NodeCheckService, VNodeMaster}
+%%      
+%%      ModFun - The function that will be called by each
+%%               VNode that is part of the coverage plan.
+%%      PrimaryVNodeCoverage - The number of primary VNodes
+%%      from the preference list to use in creating the coverage
+%%      plan.
+%%      NodeCheckService - The service to use to check for available
+%%      nodes (e.g. riak_kv).
+%%      VNodeMaster - The atom to use to reach the vnode master module.
 -module(riak_core_coverage_fsm).
 -author('Kelly McLaughlin <kelly@basho.com>').
 
@@ -65,13 +78,14 @@
 -spec behaviour_info(atom()) -> 'undefined' | [{atom(), arity()}].
 behaviour_info(callbacks) ->
     [
+     {init, 0},
      {process_results, 3}
     ];
 behaviour_info(_) ->
     undefined.
 
--type bucket() :: binary().
--type filter() :: fun() | [mfa()].
+-type bucket() :: all | binary().
+-type filter() :: none | fun() | [mfa()].
 -type req_id() :: non_neg_integer().
 -type modfun() :: {module(), fun()}.
 -type from() :: {raw, req_id(), pid()}.
@@ -97,13 +111,13 @@ behaviour_info(_) ->
 %% ===================================================================
 
 %% @doc Start a riak_core_coverage_fsm.
--spec start_link(module(), from(), fun(), list(), timeout(), atom()) ->
+-spec start_link(module(), from(), filter(), list(), timeout(), atom()) ->
                         {ok, pid()} | ignore | {error, term()}.
 start_link(Mod, From, ItemFilter, RequestArgs, Timeout, ClientType) ->
     start_link(Mod, From, all, ItemFilter, RequestArgs, Timeout, ClientType).
 
 %% @doc Start a riak_core_coverage_fsm.
--spec start_link(module(), from(), bucket(), fun(), list(), timeout(), atom()) ->
+-spec start_link(module(), from(), bucket(), filter(), list(), timeout(), atom()) ->
                         {ok, pid()} | ignore | {error, term()}.
 start_link(Mod, From, Bucket, ItemFilter, RequestArgs, Timeout, ClientType) ->
     gen_fsm:start_link(?MODULE,

src/riak_core_coverage_plan.erl

@@ -1,6 +1,6 @@
 %% -------------------------------------------------------------------
 %%
-%% riak_core_coverage_plan: TODO
+%% riak_core_coverage_plan: Create a plan to cover a minimal set of VNodes.
 %%
 %% Copyright (c) 2007-2011 Basho Technologies, Inc.  All Rights Reserved.
 %%
@@ -20,7 +20,9 @@
 %%
 %% -------------------------------------------------------------------
 
-%% @doc TODO
+%% @doc A module to calculate a plan to cover a minimal set of VNodes.
+%%      There is also an option to specify a number of primary VNodes
+%%      from each preference list to use in the plan. 
 
 -module(riak_core_coverage_plan).
 -author('Kelly McLaughlin <kelly@basho.com>').
@@ -30,11 +32,22 @@
 
 -define(RINGTOP, trunc(math:pow(2,160)-1)).  % SHA-1 space
 
+-type bucket() :: binary().
+-type index() :: non_neg_integer().
+-type req_id() :: non_neg_integer().
+-type node_indexes() :: {node(), [index()]}.
+-type coverage_vnodes() :: [{index(), node()}].
+-type vnode_filters() :: [{node(), [{index(), [index()]}]}].
+-type coverage_plan() :: {node_indexes(), coverage_vnodes(), vnode_filters()}.
+
 %% ===================================================================
 %% Public API
 %% ===================================================================
 
-%% @doc TODO
+%% @doc Create a coverage plan to distribute work to a set
+%%      covering VNodes around the ring.
+-spec create_plan(bucket(), pos_integer(), req_id(), atom()) ->
+                         {error, term()} | coverage_plan().
 create_plan(Bucket, PVC, ReqId, Service) ->
     {ok, Ring} = riak_core_ring_manager:get_my_ring(),
     case Bucket of