diff --git a/Mainpage.dox b/Mainpage.dox
--- a/Mainpage.dox
+++ b/Mainpage.dox
@@ -25,7 +25,7 @@
 - \link org::kde::kirigami::OverlaySheet  OverlaySheet \endlink
 - \link org::kde::kirigami::Theme Theme  \endlink
 - \link org::kde::kirigami::Units  Units \endlink
-- \link org::kde::kirigami::Icon Icon  \endlink
+- \link Icon Icon  \endlink
 - \link org::kde::kirigami::AbstractApplicationHeader AbstractApplicationHeader  \endlink
 - \link org::kde::kirigami::AbstractApplicationWindow AbstractApplicationWindow  \endlink
 - \link org::kde::kirigami::AbstractListItem AbstractListItem  \endlink
@@ -194,6 +194,6 @@
 
 
 // DOXYGEN_SET_RECURSIVE = YES
-// DOXYGEN_SET_EXCLUDE_PATTERNS += *_p.h */private/* */examples/*
+// DOXYGEN_SET_EXCLUDE_PATTERNS += *_p.h */private/* */examples/* */doc/*
 // DOXYGEN_SET_PROJECT_NAME = Kirigami
 // vim:ts=4:sw=4:expandtab:filetype=doxygen
diff --git a/docs/pics/icon/active.png b/docs/pics/icon/active.png
new file mode 100644
index 0000000000000000000000000000000000000000..476efc836cfd18fbdbd60da5c87f9cc319af229e
GIT binary patch
literal 5139
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

literal 0
Hc$@<O00001

diff --git a/docs/pics/icon/selected.png b/docs/pics/icon/selected.png
new file mode 100644
index 0000000000000000000000000000000000000000..d5beebfa825301c3e31700ae8d37eb3f77f5e754
GIT binary patch
literal 5711
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
LZ(eD3G3LJjKk%a=

literal 0
Hc$@<O00001

diff --git a/examples/icon/CustomSource.qml b/examples/icon/CustomSource.qml
new file mode 100644
--- /dev/null
+++ b/examples/icon/CustomSource.qml
@@ -0,0 +1,3 @@
+Kirgami.Icon {
+    source: "image://provider/kirigami.svg"
+}
\ No newline at end of file
diff --git a/examples/icon/Fallback.qml b/examples/icon/Fallback.qml
new file mode 100644
--- /dev/null
+++ b/examples/icon/Fallback.qml
@@ -0,0 +1,4 @@
+Kirgami.Icon {
+    source: "this-icon-does-not-exist"
+    fallback: "view-refresh"
+}
\ No newline at end of file
diff --git a/examples/icon/FilesystemSource.qml b/examples/icon/FilesystemSource.qml
new file mode 100644
--- /dev/null
+++ b/examples/icon/FilesystemSource.qml
@@ -0,0 +1,3 @@
+Kirgami.Icon {
+    source: "/home/example/cool.svg"
+}
\ No newline at end of file
diff --git a/examples/icon/IconThemeSource.qml b/examples/icon/IconThemeSource.qml
new file mode 100644
--- /dev/null
+++ b/examples/icon/IconThemeSource.qml
@@ -0,0 +1,3 @@
+Kirgami.Icon {
+    source: "view-refresh"
+}
\ No newline at end of file
diff --git a/examples/icon/InternetSource.qml b/examples/icon/InternetSource.qml
new file mode 100644
--- /dev/null
+++ b/examples/icon/InternetSource.qml
@@ -0,0 +1,3 @@
+Kirgami.Icon {
+    source: "https://example.com/kirigami.png"
+}
\ No newline at end of file
diff --git a/examples/icon/ResourceSource.qml b/examples/icon/ResourceSource.qml
new file mode 100644
--- /dev/null
+++ b/examples/icon/ResourceSource.qml
@@ -0,0 +1,3 @@
+Kirgami.Icon {
+    source: "qrc:/kirigami.svg"
+}
\ No newline at end of file
diff --git a/src/icon.h b/src/icon.h
--- a/src/icon.h
+++ b/src/icon.h
@@ -1,6 +1,7 @@
 /*
  *  SPDX-FileCopyrightText: 2011 Marco Martin <mart@kde.org>
  *  SPDX-FileCopyrightText: 2014 Aleix Pol Gonzalez <aleixpol@blue-systems.com>
+ *  SPDX-FileCopyrightText: 2020 Carson Black <uhhadd@gmail.com>
  *
  *  SPDX-License-Identifier: LGPL-2.0-or-later
  */
@@ -19,20 +20,111 @@
     class PlatformTheme;
 }
 
+/**
+ * Class for rendering an icon in UI.
+ */
 class Icon : public QQuickItem
 {
     Q_OBJECT
 
+    /**
+     * The source of this icon. An `Icon` can pull from:
+     * 
+     * * The icon theme:
+     * @include icon/IconThemeSource.qml
+     * * The filesystem:
+     * @include icon/FilesystemSource.qml
+     * * Remote URIs:
+     * @include icon/InternetSource.qml
+     * * Custom providers:
+     * @include icon/CustomSource.qml
+     * * Your application's bundled resources:
+     * @include icon/ResourceSource.qml
+     * 
+     * @note See https://doc.qt.io/qt-5/qtquickcontrols2-icons.html for how to
+     * bundle icon themes in your application to refer to them by name instead of
+     * by resource URL.
+     * 
+     * @note Use `fallback` to provide a fallback theme name for icons.
+     */
     Q_PROPERTY(QVariant source READ source WRITE setSource NOTIFY sourceChanged)
+
+    /**
+     * The name of a fallback icon to load from the icon theme when the `source`
+     * cannot be found. The default fallback icon is `"unknown"`.
+     * 
+     * @include icon/Fallback.qml
+     * 
+     * @note This will only be loaded if source is unavailable (e.g. it doesn't exist, or network issues have prevented loading).
+     */
+    Q_PROPERTY(QString fallback READ fallback WRITE setFallback NOTIFY fallbackChanged)
+
+    /**
+     * Whether pixmaps will be scaled smoothly if the size of this `Icon` is
+     * different from the source size.
+     */
     Q_PROPERTY(bool smooth READ smooth WRITE setSmooth NOTIFY smoothChanged)
+
+    /**
+     * The `implicitWidth` of this item, derived from the `source` image.
+     */
     Q_PROPERTY(int implicitWidth READ implicitWidth CONSTANT)
+
+    /**
+     * The `implicitHeight` of this item, derived from the `source` image.
+     */
     Q_PROPERTY(int implicitHeight READ implicitHeight CONSTANT)
+
+    /**
+     * Whether this icon will use the QIcon::Active mode when drawing the icon,
+     * resulting in a graphical effect being applied to the icon to indicate that
+     * it is currently active.
+     * 
+     * This is typically used to indicate when an item is being hovered or pressed.
+     * 
+     * @image html icon/active.png
+     * 
+     * The color differences under the default KDE color palette, Breeze. Note
+     * that a dull highlight background is typically displayed behind active icons and
+     * it is recommended to add one if you are creating a custom component.
+     */
     Q_PROPERTY(bool active READ active WRITE setActive NOTIFY activeChanged)
+
+    /**
+     * Whether this icon's `source` is valid and it is being used.
+     */
     Q_PROPERTY(bool valid READ valid NOTIFY validChanged)
+
+    /**
+     * Whether this icon will use the QIcon::Selected mode when drawing the icon,
+     * resulting in a graphical effect being applied to the icon to indicate that
+     * it is currently selected.
+     * 
+     * This is typically used to indicate when a list item is currently selected.
+     * 
+     * @image html icon/selected.png
+     * 
+     * The color differences under the default KDE color palette, Breeze. Note
+     * that a blue background is typically displayed behind selected elements.
+     */
     Q_PROPERTY(bool selected READ selected WRITE setSelected NOTIFY selectedChanged)
+
+    /**
+     * Whether this icon will be treated as a mask. When an icon is being used
+     * as a mask, all non-transparent colors are replaced with the color provided in the Icon's
+     * @link Icon::color color @endlink property.
+     * 
+     * @see color
+     */
     Q_PROPERTY(bool isMask READ isMask WRITE setIsMask NOTIFY isMaskChanged)
+
+    /**
+     * The color to use when drawing this icon when `isMask` is enabled.
+     * If this property is not set or is `Qt::transparent`, the icon will use
+     * the text or the selected text color, depending on if `selected` is set to
+     * true.
+     */
     Q_PROPERTY(QColor color READ color WRITE setColor NOTIFY colorChanged)
-    Q_PROPERTY(QString fallback READ fallback WRITE setFallback NOTIFY fallbackChanged)
 
 public:
     Icon(QQuickItem *parent = nullptr);