Comments updated

Modules/app-module/include/app/event.h

@@ -24,8 +24,8 @@ struct AppResultEventData {
     uint32_t launch_id;
     /** The child app instance's own AppMainFn/AppLoaderApi::run() return value. By convention:
      * 0 = Ok, 1 = Cancelled, 2 = Error. Apps that need to hand back more than this (e.g. picked
-     * text, a path) expose their own "get last result" getter instead - see e.g.
+     * text, a path) write it to their own stdout instead, for the caller to read via an
-     * tt::app::inputdialog::getLastText(). */
+     * AppStream bound to it. See e.g. tt::app::inputdialog::start(). */
     int32_t result;
 };
 

Modules/app-module/include/app/execute.h

@@ -17,11 +17,9 @@ extern "C" {
 
 /**
  * Starts an app directly from @a location, without it having to be pre-registered via
- * app_manager_add() first. Independent of the id-based app_start*() family
+ * app_manager_add() first.
- * (app/manager.h): performs no checks of its own beyond what AppLoaderApi::load() itself
+ * Performs no checks of its own beyond what AppLoaderApi::load() itself rejects.
- * rejects. Not manifest lookup, and not whether @a location should be allowed to run (see
+ * @warning It's advised to validate @a location with app_is_executable() first
- * app_is_executable() below): callers that need a check must run it themselves before calling
- * this.
  * @param[in] stack stack allocation config for the app's task; all-zero uses the scheduler's
  * default depth/capability, same as an AppManifest that leaves AppManifest::stack zeroed
  * @retval ERROR_NOT_FOUND no AppLoaderApi is registered for @a location.type
@@ -36,9 +34,8 @@ error_t app_execute(
 );
 
 /**
- * Same as app_execute(), but as a modal child of @a parent_instance_id - see
+ * Same as app_execute(), but as a modal child of @a parent_instance_id.
- * app_start_for_result()'s own doc for the result-delivery contract. Still no manifest
+ * See app_start_for_result()'s own doc for the result-delivery contract.
- * and no check of its own beyond what AppLoaderApi::load() itself rejects.
  * @retval ERROR_NOT_FOUND no AppLoaderApi is registered for @a location.type
  * @retval ERROR_NONE on success
  */
@@ -53,7 +50,7 @@ error_t app_execute_for_result(
 
 /**
  * Same as app_execute(), but installs @a bindings into the new instance's fd table before its
- * task begins executing - see app_start_with_streams()'s own doc for stream ownership.
+ * task begins executing. See app_start_with_streams()'s own doc for stream ownership.
  * @param[in] bindings see app_start_with_streams()
  * @retval ERROR_NOT_FOUND no AppLoaderApi is registered for @a location.type
  * @retval ERROR_OUT_OF_RANGE a binding's producer_fd is out of range
@@ -90,9 +87,9 @@ error_t app_execute_for_result_with_streams(
 );
 
 /**
- * Reports whether @a location is runnable on this target - the extension and header a loader
+ * Reports whether @a location is runnable on this target: the extension and header a loader
- * requires (e.g. an ELF's class/data/type/machine), not whether it lives anywhere in particular:
+ * requires (e.g. an ELF's class/data/type/machine), not whether it lives anywhere in particular.
- * any executable app is runnable from any path. Cheap enough to call while listing a directory.
+ * Any executable app is runnable from any path. Cheap enough to call while listing a directory.
  * @return false if @a location can't be run, or if no AppLoaderApi is registered for its type
  */
 bool app_is_executable(struct AppLocation location);

Modules/app-module/include/app/start.h

@@ -4,7 +4,7 @@
 #include <app/manager.h>
 
 /**
- * This file contains functions to start and run apps that were registerd to the app manager.
+ * This file contains functions to start and run apps that were registered to the app manager.
  * It differs from execute.h which runs executables from a specific path.
  */
 
@@ -13,29 +13,27 @@ extern "C" {
 #endif
 
 /**
- * Same as app_start(), but also passes @a argc/@a argv to the new instance's own main
+ * Starts @a id, a manifest already registered via app_manager_add(), passing @a argc/@a argv to
- * function (see app/loader.h's AppMainFn) - modelled on a C program's main(argc, argv). For
+ * the new instance's own main function (see app/loader.h's AppMainFn), modelled on a C program's
- * regular (non-modal) navigations that need to pass data to the target app (e.g. "show details
+ * main(argc, argv). For regular (non-modal) navigations that need to pass data to the target app
- * for this app id") without expecting a result back.
+ * (e.g. "show details for this app id") without expecting a result back.
  * @param[in] argv @a argc strings; app-module makes its own deep copy before returning, so
  * @a argv and the strings it points to may be freed/go out of scope immediately after this call
  * returns (e.g. safe to pass a stack-local array of a caller's own std::string::c_str()s).
+ * @retval ERROR_NOT_FOUND no manifest with this id is registered, or no AppLoaderApi is registered
+ * @retval ERROR_NONE on success
  */
 error_t app_start(const char* id, int argc, const char* const argv[], AppInstanceId* out_app_instance_id);
 
 /**
- * Starts @a id as a modal child of @a parent_instance_id, for the purpose of receiving a
+ * Starts @a id as a child of @a parent_instance_id, for the purpose of receiving a result.
- * result. The parent keeps running (window_manager's own multi-window stack handles burying its
- * window while the child is shown).
  *
- * When the child's task exits, an APP_EVENT_RESULT is delivered to @a parent_instance_id -
+ * When the child's task exits, an APP_EVENT_RESULT is delivered to @a parent_instance_id.
- * result is whatever the child's AppMainFn/AppLoaderApi::run() returned - unless
+ * The result is whatever the child's AppMainFn/AppLoaderApi::run() returned, unless
  * @a parent_instance_id is 0, in which case no result is delivered (fire-and-forget, for
  * callers with no app_instance_id of their own). The parent is then responsible for calling
- * app_manager_stop() on the child's instance id to fully reap it. Children that need to hand
+ * app_manager_stop() on the child's instance id to fully reap it.
- * back more than an int32_t (e.g. picked text, a path) expose their own "get last result"
+ *
- * getter for the parent to call after receiving the event - see e.g.
- * tt::app::inputdialog::getLastText().
  * @param[in] argv @a argc strings; app-module makes its own deep copy before returning (same as
  * app_start()), so @a argv and the strings it points to may be
  * freed/go out of scope immediately after this call returns.
@@ -62,10 +60,8 @@ error_t app_start_with_streams(const char* id, const struct AppStreamBinding* bi
  * Combines app_start_for_result() and app_start_with_streams(): starts @a id as
  * a modal child of @a parent_instance_id (see app_start_for_result()'s own doc for the
  * result-delivery contract) with @a bindings installed into its fd table before its task begins
- * executing (see app_start_with_streams()'s own doc for stream ownership). For a child
+ * executing (see app_start_with_streams()'s own doc for stream ownership).
- * that needs to hand back more than an int32_t (e.g. a path) via its own stdout instead of the
+ * For a child that needs to hand back more than an int32_t (e.g. a path) via its own stdout.
- * "get last result" getter pattern (see app_start_for_result()) - see e.g.
- * tt::app::fileselection::startForExistingFile().
  * @param[in] argv see app_start_for_result().
  * @param[in] bindings see app_start_with_streams().
  * @retval ERROR_NOT_FOUND no manifest with this id is registered, or no AppLoaderApi is registered