From d0241b27f0fc2fd65d0445fa6323b2eb12210c64 Mon Sep 17 00:00:00 2001 From: Ruslan Gadeev Date: Thu, 21 Mar 2024 05:34:18 +0300 Subject: [PATCH] Improve documentation (#293) * fix comments alignment in animation modules * escape slashes to avoid italics in haddock * fix grammar * remove onClick and onClickReq from config docs for externalLink --- src/Monomer/Core/Combinators.hs | 2 +- src/Monomer/Widgets/Animation/Fade.hs | 4 ++-- src/Monomer/Widgets/Animation/Shake.hs | 2 +- src/Monomer/Widgets/Animation/Slide.hs | 4 ++-- src/Monomer/Widgets/Animation/Transform.hs | 6 +++--- src/Monomer/Widgets/Animation/Wipe.hs | 4 ++-- src/Monomer/Widgets/Animation/Zoom.hs | 4 ++-- src/Monomer/Widgets/Singles/DateField.hs | 12 ++++++------ src/Monomer/Widgets/Singles/ExternalLink.hs | 2 -- src/Monomer/Widgets/Util/Theme.hs | 8 ++++---- src/Monomer/Widgets/Util/Widget.hs | 2 +- 11 files changed, 24 insertions(+), 26 deletions(-) diff --git a/src/Monomer/Core/Combinators.hs b/src/Monomer/Core/Combinators.hs index 493e7e5e..bad278de 100644 --- a/src/Monomer/Core/Combinators.hs +++ b/src/Monomer/Core/Combinators.hs @@ -32,7 +32,7 @@ import Monomer.Graphics.Types Given two values, usually model, checks if merge is required for a given widget. The first parameter usually corresponds to the current 'WidgetEnv', the second -to the old value/model, and the third to the new/model. +to the old value\/model, and the third to the new value\/model. This is used, for example, by _composite_ and _box_. -} diff --git a/src/Monomer/Widgets/Animation/Fade.hs b/src/Monomer/Widgets/Animation/Fade.hs index 18509e8b..a3476f00 100644 --- a/src/Monomer/Widgets/Animation/Fade.hs +++ b/src/Monomer/Widgets/Animation/Fade.hs @@ -91,7 +91,7 @@ animFadeIn managed = animFadeIn_ def managed -- | Animates a widget from not visible state to fully visible. Accepts config. animFadeIn_ :: WidgetEvent e - => [FadeCfg s e] -- ^ The config options. + => [FadeCfg s e] -- ^ The config options. -> WidgetNode s e -- ^ The child node. -> WidgetNode s e -- ^ The created animation container. animFadeIn_ configs managed = makeNode configs managed True @@ -107,7 +107,7 @@ animFadeOut managed = animFadeOut_ def managed -- | Animates a widget from visible state to not visible. Accepts config. animFadeOut_ :: WidgetEvent e - => [FadeCfg s e] -- ^ The config options. + => [FadeCfg s e] -- ^ The config options. -> WidgetNode s e -- ^ The child node. -> WidgetNode s e -- ^ The created animation container. animFadeOut_ configs managed = makeNode configs managed False diff --git a/src/Monomer/Widgets/Animation/Shake.hs b/src/Monomer/Widgets/Animation/Shake.hs index 20cfe095..adaddb1e 100644 --- a/src/Monomer/Widgets/Animation/Shake.hs +++ b/src/Monomer/Widgets/Animation/Shake.hs @@ -140,7 +140,7 @@ animShake managed = animShake_ def managed -- | Shakes a widget. Accepts config. animShake_ :: WidgetEvent e - => [ShakeCfg s e] -- ^ The config options. + => [ShakeCfg s e] -- ^ The config options. -> WidgetNode s e -- ^ The child node. -> WidgetNode s e -- ^ The created animation container. animShake_ configs managed = node where diff --git a/src/Monomer/Widgets/Animation/Slide.hs b/src/Monomer/Widgets/Animation/Slide.hs index b561959a..9eca5530 100644 --- a/src/Monomer/Widgets/Animation/Slide.hs +++ b/src/Monomer/Widgets/Animation/Slide.hs @@ -125,7 +125,7 @@ animSlideIn managed = animSlideIn_ def managed -- to left). Accepts config. animSlideIn_ :: WidgetEvent e - => [SlideCfg s e] -- ^ The config options. + => [SlideCfg s e] -- ^ The config options. -> WidgetNode s e -- ^ The child node. -> WidgetNode s e -- ^ The created animation container. animSlideIn_ configs managed = makeNode configs managed True @@ -142,7 +142,7 @@ animSlideOut managed = animSlideOut_ def managed -- visible (defaults to left). Accepts config. animSlideOut_ :: WidgetEvent e - => [SlideCfg s e] -- ^ The config options. + => [SlideCfg s e] -- ^ The config options. -> WidgetNode s e -- ^ The child node. -> WidgetNode s e -- ^ The created animation container. animSlideOut_ configs managed = makeNode configs managed False diff --git a/src/Monomer/Widgets/Animation/Transform.hs b/src/Monomer/Widgets/Animation/Transform.hs index b14ba2e2..e4276c80 100644 --- a/src/Monomer/Widgets/Animation/Transform.hs +++ b/src/Monomer/Widgets/Animation/Transform.hs @@ -212,9 +212,9 @@ animTransform f managed = animTransform_ def f managed animTransform_ :: WidgetEvent e => [TransformCfg s e] -- ^ The config options. - -> Transformer -- ^ Transformations from time (in ms) and viewport. - -> WidgetNode s e -- ^ The child node. - -> WidgetNode s e -- ^ The created animation container. + -> Transformer -- ^ Transformations from time (in ms) and viewport. + -> WidgetNode s e -- ^ The child node. + -> WidgetNode s e -- ^ The created animation container. animTransform_ configs f managed = node where node = defaultWidgetNode widgetType widget & L.info . L.focusable .~ False diff --git a/src/Monomer/Widgets/Animation/Wipe.hs b/src/Monomer/Widgets/Animation/Wipe.hs index 5d39c0e4..c69e6d5b 100644 --- a/src/Monomer/Widgets/Animation/Wipe.hs +++ b/src/Monomer/Widgets/Animation/Wipe.hs @@ -143,7 +143,7 @@ animWipeIn managed = animWipeIn_ def managed -- to left). Accepts config. animWipeIn_ :: WidgetEvent e - => [WipeCfg s e] -- ^ The config options. + => [WipeCfg s e] -- ^ The config options. -> WidgetNode s e -- ^ The child node. -> WidgetNode s e -- ^ The created animation container. animWipeIn_ configs managed = makeNode configs managed True @@ -160,7 +160,7 @@ animWipeOut managed = animWipeOut_ def managed -- visible (defaults to left). Accepts config. animWipeOut_ :: WidgetEvent e - => [WipeCfg s e] -- ^ The config options. + => [WipeCfg s e] -- ^ The config options. -> WidgetNode s e -- ^ The child node. -> WidgetNode s e -- ^ The created animation container. animWipeOut_ configs managed = makeNode configs managed False diff --git a/src/Monomer/Widgets/Animation/Zoom.hs b/src/Monomer/Widgets/Animation/Zoom.hs index dbd50243..48f9eac0 100644 --- a/src/Monomer/Widgets/Animation/Zoom.hs +++ b/src/Monomer/Widgets/Animation/Zoom.hs @@ -92,7 +92,7 @@ animZoomIn managed = animZoomIn_ def managed -- | Animates a widget to fully visible by increasing scale. Accepts config. animZoomIn_ :: WidgetEvent e - => [ZoomCfg s e] -- ^ The config options. + => [ZoomCfg s e] -- ^ The config options. -> WidgetNode s e -- ^ The child node. -> WidgetNode s e -- ^ The created animation container. animZoomIn_ configs managed = makeNode configs managed True @@ -108,7 +108,7 @@ animZoomOut managed = animZoomOut_ def managed -- | Animates a widget to not visible by decreasing scale. Accepts config. animZoomOut_ :: WidgetEvent e - => [ZoomCfg s e] -- ^ The config options. + => [ZoomCfg s e] -- ^ The config options. -> WidgetNode s e -- ^ The child node. -> WidgetNode s e -- ^ The created animation container. animZoomOut_ configs managed = makeNode configs managed False diff --git a/src/Monomer/Widgets/Singles/DateField.hs b/src/Monomer/Widgets/Singles/DateField.hs index 658baf1b..d3d4bc0a 100644 --- a/src/Monomer/Widgets/Singles/DateField.hs +++ b/src/Monomer/Widgets/Singles/DateField.hs @@ -163,9 +163,9 @@ Configuration options for dateField: - 'onChange': event to raise when the value changes. - 'onChangeReq': 'WidgetRequest' to generate when the value changes. - 'dateFormatDelimiter': which text delimiter to separate year, month and day. -- 'dateFormatDDMMYYYY': using the current delimiter, accept DD/MM/YYYY. -- 'dateFormatMMDDYYYY': using the current delimiter, accept MM/DD/YYYY. -- 'dateFormatYYYYMMDD': using the current delimiter, accept YYYY/MM/DD. +- 'dateFormatDDMMYYYY': using the current delimiter, accept DD\/MM\/YYYY. +- 'dateFormatMMDDYYYY': using the current delimiter, accept MM\/DD\/YYYY. +- 'dateFormatYYYYMMDD': using the current delimiter, accept YYYY\/MM\/DD. -} data DateFieldCfg s e a = DateFieldCfg { _dfcCaretWidth :: Maybe Double, @@ -320,19 +320,19 @@ dateFormatDelimiter delim = def { _dfcDateDelim = Just delim } --- | Date format DD/MM/YYYY, using the appropriate delimiter. +-- | Date format DD\/MM\/YYYY, using the appropriate delimiter. dateFormatDDMMYYYY :: DateFieldCfg s e a dateFormatDDMMYYYY = def { _dfcDateFormat = Just FormatDDMMYYYY } --- | Date format MM/DD/YYYY, using the appropriate delimiter. +-- | Date format MM\/DD\/YYYY, using the appropriate delimiter. dateFormatMMDDYYYY :: DateFieldCfg s e a dateFormatMMDDYYYY = def { _dfcDateFormat = Just FormatMMDDYYYY } --- | Date format YYYY/MM/DD, using the appropriate delimiter. +-- | Date format YYYY\/MM\/DD, using the appropriate delimiter. dateFormatYYYYMMDD :: DateFieldCfg s e a dateFormatYYYYMMDD = def { _dfcDateFormat = Just FormatYYYYMMDD diff --git a/src/Monomer/Widgets/Singles/ExternalLink.hs b/src/Monomer/Widgets/Singles/ExternalLink.hs index 8fab1564..ca6eb1d1 100644 --- a/src/Monomer/Widgets/Singles/ExternalLink.hs +++ b/src/Monomer/Widgets/Singles/ExternalLink.hs @@ -55,8 +55,6 @@ Configuration options for externalLink: - 'onFocusReq': 'WidgetRequest' to generate when focus is received. - 'onBlur': event to raise when focus is lost. - 'onBlurReq': 'WidgetRequest' to generate when focus is lost. -- 'onClick': event to raise when button is clicked. -- 'onClickReq': 'WidgetRequest' to generate when button is clicked. -} data ExternalLinkCfg s e = ExternalLinkCfg { _elcLabelCfg :: LabelCfg s e, diff --git a/src/Monomer/Widgets/Util/Theme.hs b/src/Monomer/Widgets/Util/Theme.hs index 31e12d67..19f83b72 100644 --- a/src/Monomer/Widgets/Util/Theme.hs +++ b/src/Monomer/Widgets/Util/Theme.hs @@ -23,7 +23,7 @@ import Monomer.Core.WidgetTypes import qualified Monomer.Core.Lens as L --- | Updates a the field of style with the field value from the active theme. +-- | Updates the field of style with the field value from the active theme. collectThemeField_ :: WidgetEnv s e -- ^ The widget environment (to get the theme). -> Lens' StyleState (Maybe t) -- ^ The target field of the style. @@ -47,9 +47,9 @@ collectThemeField_ wenv fieldStyle fieldTheme target = style where -- | Collects all the style states from a given field in the active theme. collectTheme - :: WidgetEnv s e -- ^ The widget environment (to get the theme). - -> Lens' ThemeState StyleState -- ^ The field into the theme - -> Style -- ^ The collected style. + :: WidgetEnv s e -- ^ The widget environment (to get the theme). + -> Lens' ThemeState StyleState -- ^ The field into the theme. + -> Style -- ^ The collected style. collectTheme wenv fieldT = style where basic = Just $ wenv ^. L.theme . L.basic . fieldT hover = Just $ wenv ^. L.theme . L.hover . fieldT diff --git a/src/Monomer/Widgets/Util/Widget.hs b/src/Monomer/Widgets/Util/Widget.hs index 398e286b..2077f496 100644 --- a/src/Monomer/Widgets/Util/Widget.hs +++ b/src/Monomer/Widgets/Util/Widget.hs @@ -184,7 +184,7 @@ nodeMatches oldNode newNode = infoMatches oldInfo newInfo where newInfo = newNode ^. L.info {-| -Checks if the path the node in the provided result changed compared to the old +Checks if the path of the node in the provided result changed from the old node. In case it did, it appends a SetWidgetPath request to keep track of the new location. -}