Permalink
Browse files

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

  • Loading branch information...
1 parent d6580dd commit fb9c2453cf2d782f629642faefa7a0dc2cb5aac4 Guillem Rieu committed Jun 24, 2011
@@ -45,11 +45,15 @@ 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.
**/
type DynamicResource.parameters = {
@@ -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) =
@@ -46,6 +46,10 @@ import stdlib.core.{parser, map, web.core, xhtml, rpc.maxint}
*/
/**
+ * {1 Types defined in this module}
+ */
+
+/**
* A web resource.
*
* Web resources are web pages, images, videos, etc. More generally, anything that can be accessed by a URL.
@@ -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}
*/
/**
@@ -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

0 comments on commit fb9c245

Please sign in to comment.