#lang scribble/doc
@(require scribble/manual
          scribble/eval
          planet/util
          (planet cce/scheme:7/planet)
          (planet cce/scheme:7/scribble)          
          (for-syntax scheme)
          (for-syntax (this-package-in flickr-method-info)
                      (this-package-in flickr-syntax))
          (for-label (this-package-in main))
          (for-label scheme xml))

@(define-syntax (doc-flickr stx)
   (datum->syntax stx
                  (list* 'begin
                         (map (make-method-documentation stx)
                              (force all-method-infos)))))
              
@(define the-eval
  (let ([the-eval (make-base-eval)])
    (the-eval `(require 
                (planet ,(this-package-version-symbol main))))
    #;(the-eval '(error-print-width 180))
    the-eval))

@title{@bold{Flickr}: Scheme API for Flickr}

@author+email["David Van Horn" "dvanhorn@ccs.neu.edu"]

@table-of-contents[]

@defmodule/this-package[]

@section{Overview}

This collection provides a Scheme wrapping to the Flickr web service:

   @centered[@url{http://www.flickr.com/services/api/}]

Procedures are named exactly as in the Flickr API.  Arguments are
specified with keywords spelled exactly as in the API, their values
must always be strings.  

Calling a procedure returns a list of Xexprs constituting the
[xml-payload-here] portion of the response (see the Flickr
documentation on example responses).

Here is an example call to the echo method (the value of the @scheme[api_key]
should be changed to your own key, assigned by Flickr).

@examples[#:eval the-eval
                 (flickr.test.echo #:api_key "138427ce2d97d6a2d0c4a2f045a59bfa")]

If the Flickr service responds with an error response, an exception is
raised.

@defparam[current-api-key api-key string?]{
The api_key argument is required of every method in the Flickr API.
If ommitted from a Scheme procedure call, the value defaults to the
value of the @scheme[current-api-key] parameter.  So the above could be
written as:

@examples[#:eval the-eval
   (current-api-key "138427ce2d97d6a2d0c4a2f045a59bfa")
   (flickr.test.echo)]

Methods may have required arguments and an error will be raised if
ommitted.}

@defparam[current-sec-key sec-key string?]{
Signed methods rely on the @scheme[current-sec-key] parameter for the Flickr
API secret key.}

@defparam[signed? v boolean?]{
When true, all methods are signed; when false, only methods that need signing are signed.}

@section{Example}

See example.ss for a example program that logs in a user and makes
authenticated calls to the API.

To run:

@commandline{mred-text -p dvanhorn/flickr/example}

@section{Methods}
@doc-flickr[]