diff options
author | Silvan Mosberger <contact@infinisil.com> | 2024-06-26 22:10:26 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2024-06-26 22:10:26 +0200 |
commit | dcb1f21389390fdf3aab7d6410b4c7b368c09f70 (patch) | |
tree | 52fc724014e8524829ca1fabd47ddb8dc7a4d27c /lib | |
parent | 54a93d05258a2a276d2645646f2a545fdb78f750 (diff) | |
parent | 450931d09355aa4b1a13f87bd2df0d086149879a (diff) |
Merge pull request #312412 from hsjobeki/doc/lib-gvariant
doc: migrate lib.gvariant to doc-comment format
Diffstat (limited to 'lib')
-rw-r--r-- | lib/gvariant.nix | 405 |
1 files changed, 314 insertions, 91 deletions
diff --git a/lib/gvariant.nix b/lib/gvariant.nix index 54aa4ea80571..d542df4d7b9a 100644 --- a/lib/gvariant.nix +++ b/lib/gvariant.nix @@ -1,4 +1,4 @@ -/* +/** A partial and basic implementation of GVariant formatted strings. See [GVariant Format Strings](https://docs.gtk.org/glib/gvariant-format-strings.html) for details. @@ -41,17 +41,28 @@ let variant = "v"; }; - /* Check if a value is a GVariant value - - Type: - isGVariant :: Any -> Bool - */ - isGVariant = v: v._type or "" == "gvariant"; - in rec { - inherit type isGVariant; + inherit type; + + /** + Check if a value is a GVariant value + + + # Inputs + + `v` + + : value to check + + # Type + + ``` + isGVariant :: Any -> Bool + ``` + */ + isGVariant = v: v._type or "" == "gvariant"; intConstructors = [ { @@ -100,11 +111,22 @@ rec { } ]; - /* Returns the GVariant value that most closely matches the given Nix value. - If no GVariant value can be found unambiguously then error is thrown. + /** + Returns the GVariant value that most closely matches the given Nix value. + If no GVariant value can be found unambiguously then error is thrown. - Type: - mkValue :: Any -> gvariant + + # Inputs + + `v` + + : 1\. Function argument + + # Type + + ``` + mkValue :: Any -> gvariant + ``` */ mkValue = v: if builtins.isBool v then @@ -132,14 +154,32 @@ rec { else throw "The GVariant type of “${builtins.typeOf v}” can't be inferred."; - /* Returns the GVariant array from the given type of the elements and a Nix list. + /** + Returns the GVariant array from the given type of the elements and a Nix list. + + + # Inputs - Type: - mkArray :: [Any] -> gvariant + `elems` - Example: - # Creating a string array - lib.gvariant.mkArray [ "a" "b" "c" ] + : 1\. Function argument + + # Type + + ``` + mkArray :: [Any] -> gvariant + ``` + + # Examples + :::{.example} + ## `lib.gvariant.mkArray` usage example + + ```nix + # Creating a string array + lib.gvariant.mkArray [ "a" "b" "c" ] + ``` + + ::: */ mkArray = elems: let @@ -153,31 +193,67 @@ rec { "@${self.type} [${concatMapStringsSep "," toString self.value}]"; }; - /* Returns the GVariant array from the given empty Nix list. + /** + Returns the GVariant array from the given empty Nix list. + - Type: - mkEmptyArray :: gvariant.type -> gvariant + # Inputs - Example: - # Creating an empty string array - lib.gvariant.mkEmptyArray (lib.gvariant.type.string) + `elemType` + + : 1\. Function argument + + # Type + + ``` + mkEmptyArray :: gvariant.type -> gvariant + ``` + + # Examples + :::{.example} + ## `lib.gvariant.mkEmptyArray` usage example + + ```nix + # Creating an empty string array + lib.gvariant.mkEmptyArray (lib.gvariant.type.string) + ``` + + ::: */ mkEmptyArray = elemType: mkPrimitive (type.arrayOf elemType) [ ] // { __toString = self: "@${self.type} []"; }; - /* Returns the GVariant variant from the given Nix value. Variants are containers - of different GVariant type. + /** + Returns the GVariant variant from the given Nix value. Variants are containers + of different GVariant type. + + + # Inputs + + `elem` + + : 1\. Function argument + + # Type + + ``` + mkVariant :: Any -> gvariant + ``` + + # Examples + :::{.example} + ## `lib.gvariant.mkVariant` usage example - Type: - mkVariant :: Any -> gvariant + ```nix + lib.gvariant.mkArray [ + (lib.gvariant.mkVariant "a string") + (lib.gvariant.mkVariant (lib.gvariant.mkInt32 1)) + ] + ``` - Example: - lib.gvariant.mkArray [ - (lib.gvariant.mkVariant "a string") - (lib.gvariant.mkVariant (lib.gvariant.mkInt32 1)) - ] + ::: */ mkVariant = elem: let gvarElem = mkValue elem; @@ -185,23 +261,43 @@ rec { __toString = self: "<${toString self.value}>"; }; - /* Returns the GVariant dictionary entry from the given key and value. + /** + Returns the GVariant dictionary entry from the given key and value. - Type: - mkDictionaryEntry :: String -> Any -> gvariant - Example: - # A dictionary describing an Epiphany’s search provider - [ - (lib.gvariant.mkDictionaryEntry "url" (lib.gvariant.mkVariant "https://duckduckgo.com/?q=%s&t=epiphany")) - (lib.gvariant.mkDictionaryEntry "bang" (lib.gvariant.mkVariant "!d")) - (lib.gvariant.mkDictionaryEntry "name" (lib.gvariant.mkVariant "DuckDuckGo")) - ] + # Inputs + + `name` + + : The key of the entry + + `value` + + : The value of the entry + + # Type + + ``` + mkDictionaryEntry :: String -> Any -> gvariant + ``` + + # Examples + :::{.example} + ## `lib.gvariant.mkDictionaryEntry` usage example + + ```nix + # A dictionary describing an Epiphany’s search provider + [ + (lib.gvariant.mkDictionaryEntry "url" (lib.gvariant.mkVariant "https://duckduckgo.com/?q=%s&t=epiphany")) + (lib.gvariant.mkDictionaryEntry "bang" (lib.gvariant.mkVariant "!d")) + (lib.gvariant.mkDictionaryEntry "name" (lib.gvariant.mkVariant "DuckDuckGo")) + ] + ``` + + ::: */ mkDictionaryEntry = - # The key of the entry name: - # The value of the entry value: let name' = mkValue name; @@ -212,10 +308,25 @@ rec { __toString = self: "@${self.type} {${name'},${value'}}"; }; - /* Returns the GVariant maybe from the given element type. + /** + Returns the GVariant maybe from the given element type. + + + # Inputs + + `elemType` - Type: - mkMaybe :: gvariant.type -> Any -> gvariant + : 1\. Function argument + + `elem` + + : 2\. Function argument + + # Type + + ``` + mkMaybe :: gvariant.type -> Any -> gvariant + ``` */ mkMaybe = elemType: elem: mkPrimitive (type.maybeOf elemType) elem // { @@ -226,24 +337,57 @@ rec { "just ${toString self.value}"; }; - /* Returns the GVariant nothing from the given element type. + /** + Returns the GVariant nothing from the given element type. + + + # Inputs + + `elemType` - Type: - mkNothing :: gvariant.type -> gvariant + : 1\. Function argument + + # Type + + ``` + mkNothing :: gvariant.type -> gvariant + ``` */ mkNothing = elemType: mkMaybe elemType null; - /* Returns the GVariant just from the given Nix value. + /** + Returns the GVariant just from the given Nix value. + + + # Inputs + + `elem` + + : 1\. Function argument - Type: - mkJust :: Any -> gvariant + # Type + + ``` + mkJust :: Any -> gvariant + ``` */ mkJust = elem: let gvarElem = mkValue elem; in mkMaybe gvarElem.type gvarElem; - /* Returns the GVariant tuple from the given Nix list. + /** + Returns the GVariant tuple from the given Nix list. + + + # Inputs + + `elems` + + : 1\. Function argument + + # Type - Type: - mkTuple :: [Any] -> gvariant + ``` + mkTuple :: [Any] -> gvariant + ``` */ mkTuple = elems: let @@ -255,20 +399,42 @@ rec { "@${self.type} (${concatMapStringsSep "," toString self.value})"; }; - /* Returns the GVariant boolean from the given Nix bool value. + /** + Returns the GVariant boolean from the given Nix bool value. - Type: - mkBoolean :: Bool -> gvariant + + # Inputs + + `v` + + : 1\. Function argument + + # Type + + ``` + mkBoolean :: Bool -> gvariant + ``` */ mkBoolean = v: mkPrimitive type.boolean v // { __toString = self: if self.value then "true" else "false"; }; - /* Returns the GVariant string from the given Nix string value. + /** + Returns the GVariant string from the given Nix string value. + - Type: - mkString :: String -> gvariant + # Inputs + + `v` + + : 1\. Function argument + + # Type + + ``` + mkString :: String -> gvariant + ``` */ mkString = v: let sanitize = s: replaceStrings [ "\n" ] [ "\\n" ] (escape [ "'" "\\" ] s); @@ -276,72 +442,129 @@ rec { __toString = self: "'${sanitize self.value}'"; }; - /* Returns the GVariant object path from the given Nix string value. + /** + Returns the GVariant object path from the given Nix string value. + + + # Inputs + + `v` - Type: - mkObjectpath :: String -> gvariant + : 1\. Function argument + + # Type + + ``` + mkObjectpath :: String -> gvariant + ``` */ mkObjectpath = v: mkPrimitive type.string v // { __toString = self: "objectpath '${escape [ "'" ] self.value}'"; }; - /* Returns the GVariant uchar from the given Nix int value. + /** + Returns the GVariant uchar from the given Nix int value. + + # Type - Type: - mkUchar :: Int -> gvariant + ``` + mkUchar :: Int -> gvariant + ``` */ mkUchar = mkPrimitive type.uchar; - /* Returns the GVariant int16 from the given Nix int value. + /** + Returns the GVariant int16 from the given Nix int value. - Type: - mkInt16 :: Int -> gvariant + # Type + + ``` + mkInt16 :: Int -> gvariant + ``` */ mkInt16 = mkPrimitive type.int16; - /* Returns the GVariant uint16 from the given Nix int value. + /** + Returns the GVariant uint16 from the given Nix int value. + + # Type - Type: - mkUint16 :: Int -> gvariant + ``` + mkUint16 :: Int -> gvariant + ``` */ mkUint16 = mkPrimitive type.uint16; - /* Returns the GVariant int32 from the given Nix int value. + /** + Returns the GVariant int32 from the given Nix int value. + - Type: - mkInt32 :: Int -> gvariant + # Inputs + + `v` + + : 1\. Function argument + + # Type + + ``` + mkInt32 :: Int -> gvariant + ``` */ mkInt32 = v: mkPrimitive type.int32 v // { __toString = self: toString self.value; }; - /* Returns the GVariant uint32 from the given Nix int value. + /** + Returns the GVariant uint32 from the given Nix int value. + + # Type - Type: - mkUint32 :: Int -> gvariant + ``` + mkUint32 :: Int -> gvariant + ``` */ mkUint32 = mkPrimitive type.uint32; - /* Returns the GVariant int64 from the given Nix int value. + /** + Returns the GVariant int64 from the given Nix int value. + + # Type - Type: - mkInt64 :: Int -> gvariant + ``` + mkInt64 :: Int -> gvariant + ``` */ mkInt64 = mkPrimitive type.int64; - /* Returns the GVariant uint64 from the given Nix int value. + /** + Returns the GVariant uint64 from the given Nix int value. - Type: - mkUint64 :: Int -> gvariant + # Type + + ``` + mkUint64 :: Int -> gvariant + ``` */ mkUint64 = mkPrimitive type.uint64; - /* Returns the GVariant double from the given Nix float value. + /** + Returns the GVariant double from the given Nix float value. + + + # Inputs + + `v` + + : 1\. Function argument + + # Type - Type: - mkDouble :: Float -> gvariant + ``` + mkDouble :: Float -> gvariant + ``` */ mkDouble = v: mkPrimitive type.double v // { |