Improve docs/api for frame handling

One of the pieces of the api that is very well documented is
frame/element handling - this commit adds some basic docstrings to the
frame methods, and makes the Element::new() method public.

For examples I've addedd two more commands to the www binary

- `frames` lists iframes in a page with their reference id
- `switchframe ID` switches the current context to the selected frame
- `switchframe` switches to the toplevel context

This still falls short in two areas

- there is no way to determine the current frame - AFAIK there is no
command for this in the webdriver spec
- we are missing a method to switch to the parent frame

Author: equalsraf

src/bin/www.rs

@@ -30,6 +30,11 @@ fn execute_function(name: &str, args: &str, sess: &DriverSession) -> Result<(),
                 println!("#{} {}", idx, elem.outer_html()?);
             }
         }
+        "frames" => {
+            for (idx, elem) in sess.find_elements("iframe", LocationStrategy::Css)?.iter().enumerate() {
+                println!("#{} {}", idx, elem.raw_reference());
+            }
+        }
         "windows" => {
             for (idx, handle) in sess.get_window_handles()?.iter().enumerate() {
                 println!("#{} {}", idx, handle)
@@ -45,6 +50,14 @@ fn execute_function(name: &str, args: &str, sess: &DriverSession) -> Result<(),
                 other => println!("{}", other),
             }
         }
+        "switchframe" => {
+            let arg = args.trim();
+            if arg.is_empty() {
+                try!(sess.switch_to_frame(JsonValue::Null));
+            } else {
+                try!(sess.switch_to_frame(try!(Element::new(sess, arg.to_string()).reference())));
+            }
+        }
         _ => println!("Unknown function: \"{}\"", name),
     }
     Ok(())

src/lib.rs

@@ -320,6 +320,8 @@ impl DriverSession {
         Ok(v.value)
     }
 
+    /// Valid values are element references as returned by Element::reference() or null to switch
+    /// to the top level frame
     pub fn switch_to_frame(&self, handle: JsonValue) -> Result<(), Error> {
         let _: Empty = try!(self.client.post(&format!("/session/{}/frame", self.session_id), &SwitchFrameCmd::from(handle)));
         Ok(())
@@ -340,7 +342,7 @@ pub struct Element<'a> {
 }
 
 impl<'a> Element<'a> {
-    fn new(s: &'a DriverSession, reference: String) -> Self {
+    pub fn new(s: &'a DriverSession, reference: String) -> Self {
         Element { session: s, reference: reference }
     }
 
@@ -370,11 +372,16 @@ impl<'a> Element<'a> {
         Ok(v.value)
     }
 
+    /// Returns a reference that can be passed on to the API
     pub fn reference(&self) -> Result<JsonValue, Error> {
         serde_json::to_value(&ElementReference::from_str(&self.reference))
             .map_err(|err| Error::from(err))
     }
 
+    /// The raw reference id that identifies this element, this can be used
+    /// with Element::new()
+    pub fn raw_reference(&self) -> &str { &self.reference }
+
     /// Gets the `innerHTML` javascript attribute for this element. Some drivers can get
     /// this using regular attributes, in others it does not work. This method gets it
     /// executing a bit of javascript.