[doc] review: Review of stdlib.core.web.resource

stdlib/core/web/resource/dynamic_resource.opa

@@ -45,10 +45,14 @@ import stdlib.core.{fresh, qos}
  * {1 What if I need more?}
  *
  * If you need to customize the accessibility policy of a resource, you can use
- * the function custom_publish, and provide your own consumation function, e.g. sending
+ * the function custom_publish, and provide your own consumption function, e.g. sending
  * message to some external sessions, etc.
 **/
 
+/**
+ * {1 Types defined in this module}
+ */
+
 /**
  * The default parameters for configuring the dynamic publication of a resource.
 **/
@@ -111,10 +115,10 @@ type DynamicResource.parameters.state = {
  * Url configuration, can be optional (see {!DynamicResource.publish_extend})
  */
 type DynamicResource.config = {
-  /** Means corresponding generated url will be optionaly prefixed. */
+  /** Means corresponding generated url will be optionally prefixed. */
   prefix : option(string)
 
-  /** Means corresponding generated url will be optionaly sufixed. */
+  /** Means corresponding generated url will be optionally suffixed. */
   sufix : option(string)
 
   /** A callback that be called at each url access. */
@@ -147,6 +151,10 @@ type DynamicResource.message =
  / { get : DynamicResource.key }
  / { remove : DynamicResource.key }
 
+/**
+ * {1 Interface}
+ */
+
 @server DynamicResource = {{
 
   /**
@@ -159,9 +167,9 @@ type DynamicResource.message =
       return =
         match StringMap.get(key, map) with
         | { some = ~{ resource manager } } ->
-          // !! Warning, if the semantic of cellule changes, it wont work anymore
+          // !! Warning, if the semantic of cell changes, it wont work anymore
           // currently, cell are using dynamic session, so this context is the context
-          // of the sender. If this propertie change, replace the cellule by a dynamic cellule,
+          // of the sender. If this property change, replace the cell by a dynamic cell,
           // or provide the context of the sender via the message
           if ResourceTracker.call(manager, ThreadContext.get({current}))
           then some(resource)
@@ -193,7 +201,7 @@ type DynamicResource.message =
   @private resourceCell =
     state = {map = StringMap.empty : stringmap(DynamicResource.resource);
              default = _ -> Resource.default_error_page({wrong_address})}
-    // CF remark about thread context, we may want to use a dynamic cellule instead.
+    // CF remark about thread context, we may want to use a dynamic cell instead.
     Cell.make(state, on_message)
 
   @private find_resource(key) =

stdlib/core/web/resource/resource.opa

@@ -45,6 +45,10 @@ import stdlib.core.{parser, map, web.core, xhtml, rpc.maxint}
  * [Resource.source]. To customize pages, use [Resource.full_page].
  */
 
+/**
+ * {1 Types defined in this module}
+ */
+
 /**
  * A web resource.
  *
@@ -123,10 +127,15 @@ type platform_customization =
  */
 type resource_content = external
 */
+
+/**
+ * {1 Interface}
+ */
+
 Resource = {{
 
 /**
- * {1 Constructors}
+ * {2 Constructors}
  */
 
 /**
@@ -155,7 +164,7 @@ html_constructor(title,headers,html,status,customizers,rc_lastm) =
 page(title:string, body: xhtml): resource = styled_page(title, [], body)
 
 /**
- * Build a web page, adding a set of stylesheet.
+ * Build a web page, adding a set of stylesheets.
  *
  * This function is sufficient for most uses. If you need to more control on the page, e.g. to insert platform-specific
  * changes or error codes, you should rather use function [full_page].
@@ -284,7 +293,7 @@ soap(soap: xml): resource =
 
 /**
 * Build some xmlns content
-* @param xml The contents of the xml ressource
+* @param xml The contents of the xml resource
 */
 xml(xml: xml) =
  { rc_content = {xml=xml};
@@ -298,8 +307,8 @@ xml(xml: xml) =
 *
 * This function is a more powerful variant on [soap]
 *
-* @param soap The contents of the soap ressource
-* @param status A http status for this ressource. For most ressources, you will want to use [{success}].
+* @param soap The contents of the soap resource
+* @param status A http status for this resource. For most resources, you will want to use [{success}].
 */
 full_soap(soap : xml, status: web_response) =
  { rc_content = {~soap};
@@ -353,7 +362,7 @@ json(t: RPC.Json.json) =
 
 
 /**
- * {1 Unknown resources}
+ * {2 Unknown resources}
  *
  * The following functions can be used to build resources for any other kind of content, e.g. audio, video, etc.
  */
@@ -382,7 +391,7 @@ raw_response(content: string, mimetype: string, status: web_response) =
   } : resource
 
 /**
- * Build a resource conaining only a status (empty content)
+ * Build a resource containing only a status (empty content)
  *
  * e.g. to send a 409, use [raw_status({conflict})].
  */
@@ -442,7 +451,7 @@ override_type_unsafe(content: resource, mimetype:string) : resource =
     ~rc_lastm ~rc_status} : resource
 
 /**
- * {1 Platform-specific extensions}
+ * {2 Platform-specific extensions}
  */
 
 /**
@@ -470,7 +479,7 @@ iphone_customizer(icon: string, startup_image: string, custom_css : list(string)
   | _ -> {none}
 
 /**
- * {1 Specialized constructors for errors and redirections}
+ * {2 Specialized constructors for errors and redirections}
  */
 
 /**
@@ -500,7 +509,7 @@ redirection_page(title: string, body: xhtml, status: web_response, delay: int, r
 
 
 /**
- * {2 Adding context}
+ * {3 Adding context}
  */
 
 /**
@@ -555,7 +564,7 @@ export_data({~rc_content rc_lastm=_ rc_status=_}: resource)=
     * receive information on the connexion and the user-specific information
     * associated with the given context and user.
     * @param context A user context containing information useful for building
-    * this resouce.
+    * this resource.
     *
     * @return A function which may be used in [Server.make] or [Server.secure].
     */
@@ -582,7 +591,7 @@ export_data({~rc_content rc_lastm=_ rc_status=_}: resource)=
     * servers by saturating servers with complex XML data structures that are completely unrelated
     * to the actual capabilities of the server. For better protection against Denial-of-Service
     * attack, you should consider one of the following designs:
-    * - authentifying clients before calling [in_soap_request]
+    * - authenticating clients before calling [in_soap_request]
     * - using a variant on this mechanism, such as [in_wsdl_request] (if you need XML), or
     * [in_rest_request] (for custom protocols), both of which let you define more resilient
     * services.
@@ -604,7 +613,7 @@ export_data({~rc_content rc_lastm=_ rc_status=_}: resource)=
 
 
   /**
-   * {1 Adding batches of files}
+   * {2 Adding batches of files}
    */
 
   @private get_executable_id = %% BslInit.get_executable_id %%: -> string
@@ -619,7 +628,7 @@ export_data({~rc_content rc_lastm=_ rc_status=_}: resource)=
 
 
  /**
-  * {1 Deprecated}
+  * {2 Deprecated}
   *
   * Prefer the more powerful [Server.resources] and [Server.permanent_resources].
   */
@@ -661,7 +670,7 @@ export_data({~rc_content rc_lastm=_ rc_status=_}: resource)=
 
 
 /**
- * {1 Exported to global namespace}
+ * {1 Functions exported to the global namespace}
  */
 
 /**

stdlib/core/web/resource/resource_private.opa

@@ -30,9 +30,20 @@ import stdlib.core.compare
  */
 
 /**
- * The actual contents of a resource.
+ * {1 About this module}
+ *
+ * {1 Where should I start?}
+ *
+ * {1 What if I need more?}
  */
 
+/**
+ * {1 Types defined in this module}
+ */
+
+/**
+ * The actual contents of a resource.
+ */
 type resource_private_content =
 //User-definable resources
     {html:xhtml; headers: xhtml; customizers: list(platform_customization)}
@@ -97,6 +108,11 @@ type dynamic_resource_private = { rc_name    : string;
                                   rc_lastm   : web_cache_control;
                                   rc_status  : web_response
                                 }
+
+/**
+ * {1 Interface}
+ */
+
 Resource_private =
 {{
   @private
@@ -479,7 +495,7 @@ Resource_private =
 
 
 /**
- * {1 Delivery mechanism}
+ * {2 Delivery mechanism}
  */
 
 /**
@@ -622,6 +638,7 @@ default_customizers = [customizer_for_icon,customizer_for_google_frame,required_
         }
       ]
    })
+
 /**
  * A cache for generation of xhtml resources
  */
@@ -784,7 +801,7 @@ export_resource(external_css_files: list(string),
       make_response(lastm, req, status, t ^ "; charset=utf-8", s)
 
     /**
-     * The contination to call to respond to the request
+     * The continuation to call to respond to the request
      */
     rec response(force_mimetype)(winfo:web_info, resource: resource)=
       resource_pr = resource