From ea73f75ec26cf1411486885ed8bceec5cca87a52 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Bartosz=20Dziewo=C5=84ski?= <matma.rex@gmail.com>
Date: Tue, 4 Aug 2015 18:03:30 +0200
Subject: [PATCH] mw.widgets.DateInputWidget: Add @example

Bug: T107247
Change-Id: I193fcd3175ebc96297f9d2cdd0f4de428388dd8e
---
 .../mw.widgets.CalendarWidget.js              |  2 +
 .../mw.widgets.DateInputWidget.js             | 45 +++++++++++++++++++
 2 files changed, 47 insertions(+)

diff --git a/resources/src/mediawiki.widgets/mw.widgets.CalendarWidget.js b/resources/src/mediawiki.widgets/mw.widgets.CalendarWidget.js
index 9016e895b9..2da6ae3438 100644
--- a/resources/src/mediawiki.widgets/mw.widgets.CalendarWidget.js
+++ b/resources/src/mediawiki.widgets/mw.widgets.CalendarWidget.js
@@ -10,6 +10,8 @@
 	/**
 	 * Creates an mw.widgets.CalendarWidget object.
 	 *
+	 * You will most likely want to use mw.widgets.DateInputWidget instead of CalendarWidget directly.
+	 *
 	 * @class
 	 * @extends OO.ui.Widget
 	 * @mixins OO.ui.mixin.TabIndexedElement
diff --git a/resources/src/mediawiki.widgets/mw.widgets.DateInputWidget.js b/resources/src/mediawiki.widgets/mw.widgets.DateInputWidget.js
index c20924b16f..9771e02f3c 100644
--- a/resources/src/mediawiki.widgets/mw.widgets.DateInputWidget.js
+++ b/resources/src/mediawiki.widgets/mw.widgets.DateInputWidget.js
@@ -10,6 +10,51 @@
 	/**
 	 * Creates an mw.widgets.DateInputWidget object.
 	 *
+	 *     @example
+	 *     // Date input widget showcase
+	 *     var fieldset = new OO.ui.FieldsetLayout( {
+	 *       items: [
+	 *         new OO.ui.FieldLayout(
+	 *           new mw.widgets.DateInputWidget(),
+	 *           {
+	 *             align: 'top',
+	 *             label: 'Select date'
+	 *           }
+	 *         ),
+	 *         new OO.ui.FieldLayout(
+	 *           new mw.widgets.DateInputWidget( { precision: 'month' } ),
+	 *           {
+	 *             align: 'top',
+	 *             label: 'Select month'
+	 *           }
+	 *         ),
+	 *         new OO.ui.FieldLayout(
+	 *           new mw.widgets.DateInputWidget( {
+	 *             inputFormat: 'DD.MM.YYYY',
+	 *             displayFormat: 'Do [of] MMMM [anno Domini] YYYY'
+	 *           } ),
+	 *           {
+	 *             align: 'top',
+	 *             label: 'Select date (custom formats)'
+	 *           }
+	 *         )
+	 *       ]
+	 *     } );
+	 *     $( 'body' ).append( fieldset.$element );
+	 *
+	 * The value is stored in 'YYYY-MM-DD' or 'YYYY-MM' format:
+	 *
+	 *     @example
+	 *     // Accessing values in a date input widget
+	 *     var dateInput = new mw.widgets.DateInputWidget();
+	 *     var $label = $( '<p>' );
+	 *     $( 'body' ).append( $label, dateInput.$element );
+	 *     dateInput.on( 'change', function () {
+	 *       // The value will always be a valid date or empty string, malformed input is ignored
+	 *       var date = dateInput.getValue();
+	 *       $label.text( 'Selected date: ' + ( date || '(none)' ) );
+	 *     } );
+	 *
 	 * @class
 	 * @extends OO.ui.InputWidget
 	 *
-- 
2.20.1