Fix small nits, clarfying some confusing vocabulary and using more consistent wording

diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs
index 7bedb6fd6238b744801ab4e74d78754b7822f6c4..19f3503bb842fff1b0a683649aced8f88b4ad459 100644 (file)
--- a/src/libstd/keyword_docs.rs
+++ b/src/libstd/keyword_docs.rs
@@ -1355,18 +1355,24 @@ mod super_keyword {}
 //
 /// A common interface for a group of types.
 ///
-/// A `trait` is an interface that types can implement. It is said they
-/// "implement" the trait or "conform" to the trait.
+/// A `trait` is like an interface that data types can implement. When a type
+/// implements a trait it can be treated abstractly as that trait using generics
+/// or trait objects.
 ///
-/// This interface is made up of three varieties of items:
+/// Traits can be made up of three varieties of associated items:
 ///
-/// - functions
+/// - functions and methods
 /// - types
 /// - constants
 ///
 /// Traits may also contain additional type parameters. Those type parameters
 /// or the trait itself can be constrained by other traits.
 ///
+/// Traits can serve as markers or carry other logical semantics that
+/// aren't expressed through their items. When a type implements that
+/// trait it is promising to uphold its contract. [`Send`] and [`Sync`] are two
+/// such marker traits present in the standard library.
+///
 /// See the [Reference][Ref-Traits] for a lot more information on traits.
 ///
 /// # Examples
@@ -1525,6 +1531,8 @@ mod super_keyword {}
 /// [`for`]: keyword.for.html
 /// [`impl`]: keyword.impl.html
 /// [`unsafe`]: keyword.unsafe.html
+/// [`Send`]: marker/trait.Send.html
+/// [`Sync`]: marker/trait.Sync.html
 /// [Ref-Traits]: ../reference/items/traits.html
 /// [Ref-Trait-Objects]: ../reference/types/trait-object.html
 mod trait_keyword {}