query_one docs

docs/guide/queries.md

@@ -10,17 +10,20 @@ Selectors are a very useful idea and can do more than apply styles. We can also
 
 ## Query one
 
-The [query_one][textual.dom.DOMNode.query_one] method gets a single widget in an app or other widget. If you call it with a selector it will return the first matching widget.
+The [query_one][textual.dom.DOMNode.query_one] method is used to retrieve a single widget that matches a selector or a type.
 
-Let's say we have a widget with an ID of `send` and we want to get a reference to it in our app. We could do this with the following:
+Let's say we have a widget with an ID of `send` and we want to get a reference to it in our app.
+We could do this with the following line of code:
 
 ```python
 send_button = self.query_one("#send")
 ```
 
-If there is no widget with an ID of `send`, Textual will raise a [NoMatches][textual.css.query.NoMatches] exception. Otherwise it will return the matched widget.
+This will retrieve a widget with an ID of `send`, if there is exactly one.
+If there are no matching widgets, Textual will raise a [NoMatches][textual.css.query.NoMatches] exception.
+If there are more than one match, Textual will raise a [TooManyMatches][textual.css.query.TooManyMatches] exception.
 
-You can also add a second parameter for the expected type.
+You can also add a second parameter for the expected type, which will ensure that you get the type you are expecting.
 
 ```python
 send_button = self.query_one("#send", Button)
@@ -32,9 +35,16 @@ If the matched widget is *not* a button (i.e. if `isinstance(widget, Button)` eq
 
     The second parameter allows type-checkers like MyPy to know the exact return type. Without it, MyPy would only know the result of `query_one` is a Widget (the base class).
 
+You can also specify a widget type in place of a selector, which will return a widget of that type.
+For instance, the following would return a `Button` instance (assuming there is a single Button).
+
+```python
+my_button = self.query_one(Button)
+```
+
 ## Making queries
 
-Apps and widgets have a [query][textual.dom.DOMNode.query] method which finds (or queries) widgets. This method returns a [DOMQuery][textual.css.query.DOMQuery] object which is a list-like container of widgets.
+Apps and widgets also have a [query][textual.dom.DOMNode.query] method which finds (or queries) widgets. This method returns a [DOMQuery][textual.css.query.DOMQuery] object which is a list-like container of widgets.
 
 If you call `query` with no arguments, you will get back a `DOMQuery` containing all widgets. This method is *recursive*, meaning it will also return child widgets (as many levels as required).