Clarify usage of coordinator by analysis_callgraph

* Comment in dialyzer_analysis_callgraph what the call to
  dialyzer_coordinator does;

* Delegate activation request to each dialyzer_worker;

  * There is no reason for the dialyzer_coordinator to request
    activation on behalf of the workers: let each worker request its
    own activation as it leads to more consistent dialyzer_worker
    module (activation is request as soon as status running is hit -
    reguardless of mode) and it reduces lines of code.

* Clarify types in coordinator and worker e.g. make opaque and make
  type more strict.

1 files changed, 25 insertions, 15 deletions

diff --git a/lib/dialyzer/src/dialyzer_analysis_callgraph.erl b/lib/dialyzer/src/dialyzer_analysis_callgraph.erl
index ab3e622356..59d2c2b3be 100644
--- a/lib/dialyzer/src/dialyzer_analysis_callgraph.erl
+++ b/lib/dialyzer/src/dialyzer_analysis_callgraph.erl
@@ -31,14 +31,17 @@
 
 -export([start/3]).
 
+%%% Export for dialyzer_coordinator...
 -export([compile_init_result/0,
-	 add_to_result/4,
-	 start_compilation/2,
+	 add_to_result/4]).
+%%% ... and export for dialyzer_worker.
+-export([start_compilation/2,
 	 continue_compilation/2]).
 
 -export_type([compile_init_data/0,
-	      one_file_result/0,
-	      compile_result/0]).
+              one_file_mid_error/0,
+              one_file_result_ok/0,
+              compile_result/0]).
 
 -include("dialyzer.hrl").
 
@@ -254,6 +257,10 @@ compile_and_store(Files, #analysis_state{codeserver = CServer,
   {T1, _} = statistics(wall_clock),
   Callgraph = dialyzer_callgraph:new(),
   CompileInit = make_compile_init(State, Callgraph),
+  %% Spawn a worker per file - where each worker calls
+  %% start_compilation on its file, asks next label to coordinator and
+  %% calls continue_compilation - and let coordinator aggregate
+  %% results using (compile_init_result and) add_to_result.
   {{Failed, Modules}, NextLabel} =
     ?timing(Timing, "compile", _C1,
 	    dialyzer_coordinator:parallel_job(compile, Files,
@@ -285,16 +292,18 @@ compile_and_store(Files, #analysis_state{codeserver = CServer,
   send_log(Parent, Msg2),
   {Callgraph, CServer2}.
 
--type compile_init_data() :: #compile_init{}.
--type error_reason()      :: string().
--type compile_result()    :: {[{file:filename(), error_reason()}],
-			      [module()]}. %%opaque
--type one_file_result()   :: {error, error_reason()} |
-			     {ok, [dialyzer_callgraph:callgraph_edge()],
-			      [mfa_or_funlbl()], module()}. %%opaque
--type compile_mid_data()  :: {module(), cerl:cerl(),
-			      dialyzer_callgraph:callgraph(),
-			      dialyzer_codeserver:codeserver()}.
+-opaque compile_init_data()  :: #compile_init{}.
+-type error_reason()         :: string().
+-opaque compile_result()     :: {[{file:filename(), error_reason()}],
+                                 [module()]}.
+-type one_file_mid_error()   :: {error, error_reason()}.
+-opaque one_file_result_ok() :: {ok, [dialyzer_callgraph:callgraph_edge()],
+                                 [mfa_or_funlbl()], module()}.
+-type one_file_result()      :: one_file_mid_error() |
+                                one_file_result_ok().
+-type compile_mid_data()     :: {module(), cerl:cerl(),
+                                 dialyzer_callgraph:callgraph(),
+                                 dialyzer_codeserver:codeserver()}.
 
 -spec compile_init_result() -> compile_result().
 
@@ -435,7 +444,8 @@ store_core(Mod, Core, Callgraph, CServer) ->
   CoreSize = cerl_trees:size(CoreTree),
   {ok, CoreSize, {Mod, CoreTree, Callgraph, CServer}}.
 
--spec continue_compilation(integer(), compile_mid_data()) -> one_file_result().
+-spec continue_compilation(integer(), compile_mid_data()) ->
+                              one_file_result_ok().
 
 continue_compilation(NextLabel, {Mod, CoreTree, Callgraph, CServer}) ->
   {LabeledTree, _NewNextLabel} = cerl_trees:label(CoreTree, NextLabel),