Document the new inheritance machinery (fixes #8125)

components/script/dom/mod.rs

@@ -54,21 +54,39 @@
 //! This invariant is enforced by the lint in
 //! `plugins::lints::inheritance_integrity`.
 //!
-//! The same principle applies to typeids,
+//! Interfaces which either derive from or are derived by other interfaces
-//! the derived type enum should
+//! implement the `Castable` trait, which provides three methods `is::<T>()`,
-//! use one addititional type (the parent class) because sometimes the parent
+//! `downcast::<T>()` and `upcast::<T>()` to cast across the type hierarchy
-//! can be the most-derived class of an object.
+//! and check whether a given instance is of a given type.
 //!
 //! ```ignore
-//! pub enum EventTypeId {
+//! use dom::bindings::conversions::Castable;
-//!     UIEvent(UIEventTypeId),
+//! use dom::element::Element;
-//!     //others events
+//! use dom::htmlelement::HTMLElement;
-//! }
+//! use dom::htmlinputelement::HTMLInputElement;
 //!
-//! pub enum UIEventTypeId {
+//! if let Some(elem) = node.downcast::<Element> {
-//!    MouseEvent,
+//!     if elem.is::<HTMLInputElement>() {
-//!    KeyboardEvent,
+//!         return elem.upcast::<HTMLElement>();
-//!    UIEvent, //<- parent of MouseEvent and KeyboardEvent
+//!     }
+//! }
+//! ```
+//!
+//! Furthermore, when discriminating a given instance against multiple
+//! interface types, code generation provides a convenient TypeId enum
+//! which can be used to write `match` expressions instead of multiple
+//! calls to `Castable::is::<T>`. The `type_id()` method of an instance is
+//! provided by the farthest interface it derives from, e.g. `EventTarget`
+//! for `HTMLMediaElement`. For convenience, that method is also provided
+//! on the `Node` interface to avoid unnecessary upcasts to `EventTarget`.
+//!
+//! ```ignore
+//! use dom::bindings::codegen::InheritTypes::{EventTargetTypeId, NodeTypeId};
+//!
+//! match *node.type_id() {
+//!     EventTargetTypeId::Node(NodeTypeId::CharacterData(_)) => ...,
+//!     EventTargetTypeId::Node(NodeTypeId::Element(_)) => ...,
+//!     ...,
 //! }
 //! ```
 //!