Documentation and some other stuff.

scrbl/wv-settings.scrbl

@@ -1,69 +1,117 @@
 #lang scribble/manual
 
-@(require scribble/racket
-          scribble/example
+@(require racket/base
+          racket/class
           scribble/core
           (for-label racket/base
                      racket/string
                      racket/class
-                     racket/file)
-          )
+                     racket/file))
 
-@defmodule[racket-webview]
-
-@title{Object-Oriented Interface: @racket[wv-settings%]}
+@title{wv-settings}
 @author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
 
+@defmodule[wv-settings]
+
+Settings wrapper used by the webview library.
+
+This module exports the @racket[wv-settings%] class, which provides a small
+object-oriented interface over an @racket[ini] settings backend. Settings are
+accessed relative to a context.
+
+@section{Overview}
+
+A @racket[wv-settings%] object combines:
+
+@itemlist[#:style 'compact
+ @item{an @racket[ini] settings object}
+ @item{a @racket[symbol] identifying the settings context}]
+
+Keys used in this class are symbols.
+
+@section{Class: wv-settings%}
+
 @defclass[wv-settings% object% ()]{
 
-An OO wrapper around a settings backend implementing, e.g. @racket[simple-ini/class].  
-A @racket[wv-settings%] object represents a view on one settings section.
-The supplied @racket[wv-context] value is used as the section identifier for
-context-local settings. The class delegates all actual storage operations to the supplied
-@racket[ini] object.
+Wraps an @racket[ini] settings object for one context.
 
-@defconstructor[([ini object?]
+The class delegates all reads and writes to the supplied @racket[ini] object.
+
+@defconstructor[([ini (is-a?/c ini%)]
                  [wv-context symbol?])]{
-Creates a new settings object. The @racket[ini] argument is the backing settings object.
-The @racket[wv-context] argument is used as the section identifier for
-context-local settings. The class assumes that @racket[ini] supports methods compatible with:
 
-@itemlist[#:style 'compact
- @item{@racket[(send ini get section key)]}
- @item{@racket[(send ini get section key default)]}
- @item{@racket[(send ini set! section key value)]}
+Creates a settings wrapper.
+
+@racket[ini] must provide compatible @racket[get] and @racket[set!] methods.
+@racket[wv-context] is the context symbol used for contextual settings access.
+}
+
+@defmethod[(get [key symbol?] [default-value any/c] ...) any/c]{
+
+Returns the value associated with @racket[key] in the current context.
+
+If no default value is supplied, the call delegates to:
+
+@racketblock[
+(send ini get wv-context key)
+]
+
+If a default value is supplied, only the first extra argument is used, and the
+call delegates to:
+
+@racketblock[
+(send ini get wv-context key default)
 ]
 }
 
-@defmethod*[([(get [key symbol?]) any/c]
-             [(get [key symbol?] [default-value any/c]) any/c])]{
-Returns the value associated with @racket[key] in the current section. 
-Returns @tt{default-value} (when supplied) if the key is not found. 
+@defmethod[(set! [key symbol?] [value any/c]) any/c]{
+
+Stores @racket[value] under @racket[key] in the current context.
+
+Delegates to:
+
+@racketblock[
+(send ini set! wv-context key value)
+]
 }
 
-@defmethod*[([(set! [key symbol?] [value any/c]) this])]{
-Stores @racket[value] under @racket[key] in the current section.
+@defmethod[(get/global [key symbol?] [default-value any/c] ...) any/c]{
+
+Returns the value associated with @racket[key] in the global settings section.
+
+If no default value is supplied, the call delegates to:
+
+@racketblock[
+(send ini get 'global key)
+]
+
+If a default value is supplied, only the first extra argument is used, and the
+call delegates to:
+
+@racketblock[
+(send ini get 'global key default)
+]
 }
 
-@defmethod*[([(get/global [key symbol?]) any/c]
-             [(get/global [key symbol?] [default-value any/c]) any/c])]{
-Returns the value associated with @racket[key] in the global section.
-This method delegates to @tt{(send ini get 'global key default-value)}.
+@defmethod[(set/global! [key symbol?] [value any/c]) any/c]{
+
+Stores @racket[value] under @racket[key] in the global settings section.
+
+Delegates to:
+
+@racketblock[
+(send ini set! 'global key value)
+]
 }
 
-@defmethod*[([(set/global! [key symbol?] [value any/c]) this])]{
-Stores @racket[value] under @racket[key] in the global section. 
-Delegates to @tt{(send ini set! 'global key value)}.
+@defmethod[(clone [context symbol?]) wv-settings%]{
+
+Creates a new @racket[wv-settings%] object sharing the same @racket[ini]
+backend but using @racket[context] as its context.
 }
 
-@defmethod*[([(clone [context any/c]) (is-a?/c wv-settings%)])]{
-Creates a new @racket[wv-settings%] object using the same
-@racket[ini] backend but with another section identifier.
-It is intended to support cheap creation of per-section settings views.
-}
+@defmethod[(context) symbol?]{
 
-@defmethod*[([(context) symbol?])]{
-Returns the section identifier associated with this settings object.
+Returns the current context symbol.
 }
-
 }