Documentation and some other stuff.

scrbl/wv-context.scrbl

@@ -1,80 +1,107 @@
 #lang scribble/manual
 
-@(require scribble/racket
-          scribble/example
+@(require racket/base
+          racket/class
           scribble/core
           (for-label racket/base
+                     racket/string
                      racket/class
-                     racket/path
-                     "../private/wv-settings.rkt"
-                     "../private/racket-webview.rkt")
-          )
+                     racket/file))
 
-@defmodule[racket-webview]
+@;          "../private/wv-context.rkt")
 
-@title{Object-Oriented Interface: @racket[wv-context%]}
+@title{wv-context}
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 
+@defmodule[wv-context]
+
+@section{Overview}
+
+The library is organized around two main concepts: contexts and windows.
+
+A context represents the shared runtime environment for one or more webview
+windows. It owns the underlying webview context, provides the base URL used by
+those windows, and gives access to persistent settings through
+@racketmodname[wv-settings].
+
+This module exports the @racket[wv-context%] class.
+
 @defclass[wv-context% object% ()]{
 
-An OO wrapper around a webview context together with its associated settings.
-A @racket[wv-context%] object creates and owns a webview context by calling
-@racket[webview-new-context]. It also creates a corresponding @racket[wv-settings%]
-instance for access to global and per-section settings. This class manages
-construction of a webview context using a file getter and boilerplate JavaScript, 
-exposure of the created low-level context object via @racket[context], 
-access to the base URL of the created context via @racket[base-url] and
-access to settings views via @racket[settings].
+Represents a webview context.
+
+A @racket[wv-context%] object is a thin class-based wrapper around the
+higher-level context support provided by @racketmodname[racket-webview]. It
+creates and stores a @racket[wv-context] value internally and provides methods
+to access that value, its base URL, and a settings object.
 
 @defconstructor[([base-path path-string?]
-                 [file-getter procedure? (webview-standard-file-getter base-path)]
-                 [context-js procedure? (λ () "")]
-                 [boilerplate-js procedure? (webview-default-boilerplate-js context-js)]
-                 [ini object?])]{
-Creates a new @racket[wv-context%] object.
+                 [file-getter procedure?
+                              (webview-standard-file-getter base-path)]
+                 [context-js procedure?
+                             (λ () "")]
+                 [boilerplate-js string?
+                                 (webview-default-boilerplate-js context-js)]
+                 [ini any/c
+                      (error "You need to provide a 'ini' file settings interface for settings, e.g. simple-ini/class")])]{
 
-The @racket[base-path] argument is used to construct the default
-@racket[file-getter].
+Creates a new context object.
 
-The @racket[file-getter] argument is passed to @racket[webview-new-context]
-and is responsible for resolving files served by the context.
-
-The @racket[context-js] argument must be a procedure producing the JavaScript
-snippet that should be injected into the context.
-
-The @racket[boilerplate-js] argument must be a procedure producing the final
-boilerplate JavaScript used when constructing the context. By default it is
-built from @racket[context-js] using @racket[webview-default-boilerplate-js].
-
-The @racket[ini] argument is mandatory and supplies the settings backend used
-for construction of the internal @racket[wv-settings%] object. If omitted, the
-constructor raises an error.
-
-During initialization the class:
+The constructor accepts the following initialization fields.
 
 @itemlist[#:style 'compact
- @item{creates a new low-level context with @racket[webview-new-context];}
- @item{creates a @racket[wv-settings%] object using @racket[ini] and the
-       global context identifier @racket['global].}
+ @item{@racket[base-path] is the base path used by the default file getter.}
+ @item{@racket[file-getter] is the procedure used to resolve files for the
+       local web server. Its default value is
+       @racket[(webview-standard-file-getter base-path)].}
+ @item{@racket[context-js] is a procedure producing additional JavaScript for
+       the context. Its default value is @racket[(λ () "")].}
+ @item{@racket[boilerplate-js] is the JavaScript boilerplate installed into the
+       underlying webview context. Its default value is
+       @racket[(webview-default-boilerplate-js context-js)].}
+ @item{@racket[ini] is the settings backend used to construct the associated
+       @racket[wv-settings%] object. No default backend is provided; omitting it
+       raises an error.}]
+
+After @racket[super-new], the constructor creates the underlying
+@racket[wv-context] value using @racket[webview-new-context], and then creates a
+settings object using:
+
+@racketblock[
+(new wv-settings% [ini ini] [wv-context 'global])
 ]
+
+The settings object is stored internally and used by the
+@racket[settings] method.
 }
 
-@defmethod*[([(context) wv-context?])]{
-Returns the underlying webview context (struct) created during
-initialization.
+@defmethod[(context) wv-context?]{
+
+Returns the internal context value created by @racket[webview-new-context].
+
+This is the underlying @racketmodname[racket-webview] context object used by
+the rest of the library.
 }
 
-@defmethod*[([(settings [section symbol?]) (is-a?/c wv-settings%)])] {
-Returns a @tt{wv-settings%} object for @racket[section]. 
-This method delegates to the internally stored @racket[wv-settings%] object by
-calling @racket[(send settings-obj clone section)]. The resulting object shares
-the same @racket[ini] backend as the global settings object, but addresses the
-supplied section.
+@defmethod[(settings [section symbol?]) wv-settings%]{
+
+Returns a cloned settings object for @racket[section].
+
+The method delegates to the internal @racket[wv-settings%] instance as:
+
+@racketblock[
+(send settings-obj clone section)
+]
+
+This allows per-section settings access while preserving the original settings
+object stored by the context.
 }
 
-@defmethod*[([(base-url) any/c])] {
-Returns the base URL of the underlying webview context.
-This method delegates to @racket[wv-context-base-url].
-}
+@defmethod[(base-url) string?]{
 
+Returns the base URL of the underlying context.
+
+The method delegates to @racket[wv-context-base-url] applied to the internal
+context value.
 }
+}