Merge pull request #3263 from Aire-One/doc_textclock

[doc] Improve wibox.widget.textclock format documentation

.travis.yml

@@ -239,7 +239,9 @@ script:
         && grep -q 'May not access' lib/beautiful/init.lua
     fi
   - |
-    set -e
+    trap 'echo ERR CODE $? from $BASH_COMMAND : $LINENO' ERR
+    trap 'echo EXIT CODE $? from $BASH_COMMAND : $LINENO' EXIT
+    set -ex
     if [ -n "$BUILD_IN_DIR" ]; then
       # Explicitly remove the Makefile to not build from the src dir accidentally.
       rm Makefile
@@ -289,7 +291,7 @@ script:
     fi
   - |
     if [ "$TEST_PREV_COMMITS" = 1 ] && ! [ "$TRAVIS_PULL_REQUEST" = false ]; then
-      set -e
+      set -ex
       # Check each commit separately (to make git-bisect less annoying).
       # Fix Travis' commit range (https://github.com/travis-ci/travis-ci/issues/4596).
       commit_range="${TRAVIS_COMMIT_RANGE/.../..}"
@@ -330,7 +332,9 @@ after_success:
   - if [ "$BUILD_APIDOC" = "true" ]; then build-utils/travis-apidoc.sh; fi
   # Push code coverage information
   - |
-    set -e
+    trap 'echo ERR CODE $? from $BASH_COMMAND : $LINENO' ERR
+    trap 'echo EXIT CODE $? from $BASH_COMMAND : $LINENO' EXIT
+    set -ex
     if [ "$DO_COVERAGE" = "coveralls" ]; then
       test -f build/luacov.stats.out || { echo 'build/luacov.stats.out does not exist.'; return 1; }
       luacov-coveralls --verbose --merge

docs/common/glib_timedate_format.ldoc

@@ -0,0 +1,28 @@
+--<table class='widget_list' border=1>
+-- <tr>
+--   <th align='center'>Format</th>
+--   <th align='center'>Description</th>
+-- </tr>
+--   <tr><td>%a</td><td>The abbreviated weekday name according to the current locale</td></tr>
+--   <tr><td>%A</td><td>the full weekday name according to the current locale</td></tr>
+--   <tr><td>%b</td><td>The abbreviated month name according to the current locale</td></tr>
+--   <tr><td>%B</td><td>The full month name according to the current locale</td></tr>
+--   <tr><td>%d</td><td>The day of the month as a decimal number (range 01 to 31)</td></tr>
+--   <tr><td>%e</td><td>The day of the month as a decimal number (range 1 to 31)</td></tr>
+--   <tr><td>%F</td><td>Equivalent to %Y-%m-%d (the ISO 8601 date format)</td></tr>
+--   <tr><td>%H</td><td>The hour as a decimal number using a 24-hour clock (range 00 to 23)</td></tr>
+--   <tr><td>%I</td><td>The hour as a decimal number using a 12-hour clock (range 01 to 12)</td></tr>
+--   <tr><td>%k</td><td>The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank</td></tr>
+--   <tr><td>%l</td><td>The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank</td></tr>
+--   <tr><td>%m</td><td>The month as a decimal number (range 01 to 12)</td></tr>
+--   <tr><td>%M</td><td>The minute as a decimal number (range 00 to 59)</td></tr>
+--   <tr><td>%p</td><td>Either "AM" or "PM" according to the given time value, or the corresponding strings for the current locale. Noon is treated as "PM" and midnight as "AM".</td></tr>
+--   <tr><td>%P</td><td>Like %p but lowercase: "am" or "pm" or a corresponding string for the current locale</td></tr>
+--   <tr><td>%r</td><td>The time in a.m. or p.m. notation</td></tr>
+--   <tr><td>%R</td><td>The time in 24-hour notation (%H:%M)</td></tr>
+--   <tr><td>%S</td><td>The second as a decimal number (range 00 to 60)</td></tr>
+--   <tr><td>%T</td><td>The time in 24-hour notation with seconds (%H:%M:%S)</td></tr>
+--   <tr><td>%y</td><td>The year as a decimal number without the century</td></tr>
+--   <tr><td>%Y</td><td>The year as a decimal number including the century</td></tr>
+--   <tr><td>%%</td><td>A literal % character</td></tr>
+-- </table>

lib/wibox/widget/textclock.lua

@@ -1,6 +1,42 @@
 ---------------------------------------------------------------------------
 --- Text clock widget.
 --
+-- The `wibox.widget.textclock` widget is part of the Awesome WM's widget
+-- system (see @{03-declarative-layout.md}).
+--
+-- This widget displays a text clock formatted by the
+-- [GLib Date Time format](https://developer.gnome.org/glib/stable/glib-GDateTime.html#g-date-time-format)
+-- and [GTimeZone](https://developer.gnome.org/glib/stable/glib-GTimeZone.html#g-time-zone-new).
+--
+-- The `wibox.widget.textclock` inherits from `wibox.widget.textbox`. It means
+-- that, once created, the user will receive a derivated instance of
+-- `wibox.widget.textbox` associated with a private `gears.timer` to manage
+-- timed updates of the displayed clock.
+--
+-- Use a `wibox.widget.textclock`
+-- ---
+--
+-- @DOC_wibox_widget_defaults_textclock_EXAMPLE@
+--
+-- Alternatively, you can declare the `textclock` widget using the
+-- declarative pattern (Both codes are strictly equivalent):
+--
+-- @DOC_wibox_widget_declarative-pattern_textclock_EXAMPLE@
+--
+-- The GLib DateTime format
+-- ---
+--
+-- The time displayed by the textclock widget can be formated by the GLib
+-- DateTime format.
+--
+-- Here is a short list with commonly used format specifiers (extracted from
+-- the Glib API references):
+--
+--@DOC_glib_timedate_format_COMMON@
+--
+-- You can read more on the GLib DateTime format in the
+-- [GLib documentation](https://developer.gnome.org/glib/stable/glib-GDateTime.html#g-date-time-format).
+--
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2009 Julien Danjou
 -- @widgetmod wibox.widget.textclock

tests/examples/wibox/widget/declarative-pattern/textclock.lua

@@ -0,0 +1,12 @@
+--DOC_NO_USAGE
+local parent = ... --DOC_HIDE
+local wibox = require("wibox") --DOC_HIDE
+
+    local my_textclock = wibox.widget {
+        format = '%a %b %d, %H:%M',
+        widget = wibox.widget.textclock
+    }
+
+parent:add(my_textclock) --DOC_HIDE
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/widget/defaults/textclock.lua

@@ -0,0 +1,10 @@
+--DOC_GEN_IMAGE
+--DOC_NO_USAGE
+local parent = ... --DOC_HIDE
+local wibox = require("wibox") --DOC_HIDE
+
+    local my_textclock = wibox.widget.textclock('%a %b %d, %H:%M')
+
+parent:add(my_textclock) --DOC_HIDE
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80