From 4bb816f41efc197a1a2a02d2a17a7025a7578243 Mon Sep 17 00:00:00 2001
From: Sean Yang <seany314@gmail.com>
Date: Wed, 17 Jul 2024 13:41:19 -0700
Subject: [PATCH] address comments

---
 .../controllers/model_controller.rst                | 13 ++++++++++++-
 .../app_common/workflows/base_model_controller.py   |  2 +-
 nvflare/app_common/workflows/model_controller.py    |  2 +-
 3 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/docs/programming_guide/controllers/model_controller.rst b/docs/programming_guide/controllers/model_controller.rst
index 6d3f012345..c9aa1aa94e 100644
--- a/docs/programming_guide/controllers/model_controller.rst
+++ b/docs/programming_guide/controllers/model_controller.rst
@@ -112,6 +112,16 @@ Below is a comprehensive table overview of the :class:`ModelController<nvflare.a
 Communication
 =============
 
+The ModelController uses a task based communication where tasks are sent to targets, and targets execute the tasks and return results.
+The :ref:`fl_model` is standadized data structure object that can be sent along with each task, and :ref:`fl_model` responses are received for the results.
+
+.. note::
+
+    The :ref:`fl_model` object can be any type of data.
+    For example, in the "train" and "validate" tasks we send the model parameters along with the task so the target clients can train and validate the model.
+    However in many other tasks that do not involve sending the model (e.g. "submit_model"), the :ref:`fl_model` can contain any type of data (e.g. metadata, metrics etc.) or may be not be needed at all.
+
+
 send_model_and_wait
 -------------------
 :func:`send_model_and_wait<nvflare.app_common.workflows.model_controller.ModelController.send_model_and_wait>` is the core communication function which enables users to send tasks to targets, and wait for responses.
@@ -215,7 +225,8 @@ For the JobAPI, define the controller and send it to the server.
   )
   job.to(controller, "server")
 
-The controller can also be configured in ``config_fed_server.json`` in the workflows section.
+The above JobAPI code will automatically generate the server configuration for the controller.
+The controller can also be configured manually in ``config_fed_server.json`` in the workflows section.
 
 Examples
 ========
diff --git a/nvflare/app_common/workflows/base_model_controller.py b/nvflare/app_common/workflows/base_model_controller.py
index 3310a5014b..a588f9d7b8 100644
--- a/nvflare/app_common/workflows/base_model_controller.py
+++ b/nvflare/app_common/workflows/base_model_controller.py
@@ -350,7 +350,7 @@ def save_model(self, model):
         else:
             self.error("persistor not configured, model will not be saved")
 
-    def sample_clients(self, num_clients=None):
+    def sample_clients(self, num_clients: int = None) -> List[str]:
         clients = [client.name for client in self.engine.get_clients()]
 
         if num_clients:
diff --git a/nvflare/app_common/workflows/model_controller.py b/nvflare/app_common/workflows/model_controller.py
index 125a6ffc97..1c2570919e 100644
--- a/nvflare/app_common/workflows/model_controller.py
+++ b/nvflare/app_common/workflows/model_controller.py
@@ -128,6 +128,6 @@ def sample_clients(self, num_clients: int = None) -> List[str]:
         Args:
             num_clients: number of clients to return. If None or > number available clients, returns all available clients. Defaults to None.
 
-        Returns: list of clients.
+        Returns: list of clients names.
         """
         return super().sample_clients(num_clients)