Docs: migrate format of comments to doc-comments (#381381) (642babe8) · Commits · nix / nixpkgs

.git-blame-ignore-revs

+6 −0

Original line number	Diff line number	Diff line
		@@ -229,3 +229,9 @@ adb9714bd909df283c66bbd641bd631ff50a4260

		# tmuxPlugins sha-to-sri.py script
		516b1e74c358a9c4b06e5591f8c1a2897aad0c33

		# treewide: migrate comments in lib to rfc145 style
		ef85e0daa092c9eae0d32c7ce16b889728a5fbc0
		d89ad6c70e0e89aaae75e9f886878ea4e103965a
		e0fe216f4912dd88a021d12a44155fd2cfeb31c8
		80d5b411f6397d5c3e755a0635d95742f76f3c75

lib/fileset/internal.nix

+32 −4

Original line number	Diff line number	Diff line
		@@ -267,7 +267,7 @@ rec {
		# Set all entries not present to null
		mapAttrs (name: value: null) (readDir path) // value;

		/*
		/**
		A normalisation of a filesetTree suitable filtering with `builtins.path`:
		- Replace all directories that have no files with `null`.
		This removes directories that would be empty
		@@ -276,7 +276,21 @@ rec {

		Note that this function is strict, it evaluates the entire tree

		Type: Path -> filesetTree -> filesetTree
		# Inputs

		`path`

		: 1\. Function argument

		`tree`

		: 2\. Function argument

		# Type

		```
		Path -> filesetTree -> filesetTree
		```
		*/
		_normaliseTreeFilter =
		path: tree:
		@@ -298,7 +312,7 @@ rec {
		else
		tree;

		/*
		/**
		A minimal normalisation of a filesetTree, intended for pretty-printing:
		- If all children of a path are recursively included or empty directories, the path itself is also recursively included
		- If all children of a path are fully excluded or empty directories, the path itself is an empty directory
		@@ -307,7 +321,21 @@ rec {

		Note that this function is partially lazy.

		Type: Path -> filesetTree -> filesetTree (with "emptyDir"'s)
		# Inputs

		`path`

		: 1\. Function argument

		`tree`

		: 2\. Function argument

		# Type

		```
		Path -> filesetTree -> filesetTree (with "emptyDir"'s)
		```
		*/
		_normaliseTreeMinimal =
		path: tree:

lib/licenses.nix

+8 −5

Original line number	Diff line number	Diff line
		@@ -24,9 +24,10 @@ let

		in
		lib.mapAttrs mkLicense ({
		/* License identifiers from spdx.org where possible.
		* If you cannot find your license here, then look for a similar license or
		* add it to this list. The URL mentioned above is a good source for inspiration.
		/**
		License identifiers from spdx.org where possible.
		If you cannot find your license here, then look for a similar license or
		add it to this list. The URL mentioned above is a good source for inspiration.
		*/

		abstyles = {
		@@ -37,7 +38,9 @@ lib.mapAttrs mkLicense ({
		acsl14 = {
		fullName = "Anti-Capitalist Software License v1.4";
		url = "https://anticapitalist.software/";
		/* restrictions on corporations apply for both use and redistribution */
		/**
		restrictions on corporations apply for both use and redistribution
		*/
		free = false;
		redistributable = false;
		};

lib/modules.nix

+424 −179

Original line number	Diff line number	Diff line
		@@ -74,14 +74,16 @@ let
		decls
		));

		/* See https://nixos.org/manual/nixpkgs/unstable/#module-system-lib-evalModules
		/**
		See https://nixos.org/manual/nixpkgs/unstable/#module-system-lib-evalModules
		or file://./../doc/module-system/module-system.chapter.md

		!!! Please think twice before adding to this argument list! The more
		that is specified here instead of in the modules themselves the harder
		it is to transparently move a set of modules to be a submodule of another
		config (as the proper arguments need to be replicated at each call to
		evalModules) and the less declarative the module set is. */
		evalModules) and the less declarative the module set is.
		*/
		evalModules = evalModulesArgs@
		{ modules
		, prefix ? []
		@@ -378,7 +380,7 @@ let
		else
		m: m;

		/*
		/**
		Collects all modules recursively into the form

		{
		@@ -459,12 +461,42 @@ let
		in modulesPath: initialModules: args:
		filterModules modulesPath (collectStructuredModules unknownModule "" initialModules args);

		/* Wrap a module with a default location for reporting errors. */
		/**
		Wrap a module with a default location for reporting errors.


		# Inputs

		`file`

		: 1\. Function argument

		`m`

		: 2\. Function argument
		*/
		setDefaultModuleLocation = file: m:
		{ _file = file; imports = [ m ]; };

		/* Massage a module into canonical form, that is, a set consisting
		of ‘options’, ‘config’ and ‘imports’ attributes. */
		/**
		Massage a module into canonical form, that is, a set consisting
		of ‘options’, ‘config’ and ‘imports’ attributes.


		# Inputs

		`file`

		: 1\. Function argument

		`key`

		: 2\. Function argument

		`m`

		: 3\. Function argument
		*/
		unifyModuleSyntax = file: key: m:
		let
		addMeta = config: if m ? meta
		@@ -528,7 +560,8 @@ let
		# works.
		in f (args // extraArgs);

		/* Merge a list of modules. This will recurse over the option
		/**
		Merge a list of modules. This will recurse over the option
		declarations in all modules, combining them into a single set.
		At the same time, for each option declaration, it will merge the
		corresponding option definitions in all machines, returning them
		@@ -548,6 +581,17 @@ let
		...
		];
		}


		# Inputs

		`prefix`

		: 1\. Function argument

		`modules`

		: 2\. Function argument
		*/
		mergeModules = prefix: modules:
		mergeModules' prefix modules
		@@ -740,7 +784,8 @@ let
		in
		throw (concatStringsSep "\n\n" paragraphs);

		/* Merge multiple option declarations into a single declaration. In
		/**
		Merge multiple option declarations into a single declaration. In
		general, there should be only one declaration of each option.
		The exception is the ‘options’ attribute, which specifies
		sub-options. These can be specified multiple times to allow one
		@@ -750,7 +795,19 @@ let
		'loc' is the list of attribute names where the option is located.

		'opts' is a list of modules. Each module has an options attribute which
		correspond to the definition of 'loc' in 'opt.file'. */
		correspond to the definition of 'loc' in 'opt.file'.


		# Inputs

		`loc`

		: 1\. Function argument

		`opts`

		: 2\. Function argument
		*/
		mergeOptionDecls =
		loc: opts:
		foldl' (res: opt:
		@@ -819,8 +876,25 @@ let
		} // typeSet
		) { inherit loc; declarations = []; declarationPositions = []; options = []; } opts;

		/* Merge all the definitions of an option to produce the final
		config value. */
		/**
		Merge all the definitions of an option to produce the final
		config value.


		# Inputs

		`loc`

		: 1\. Function argument

		`opt`

		: 2\. Function argument

		`defs`

		: 3\. Function argument
		*/
		evalOptionValue = loc: opt: defs:
		let
		# Add in the default value for this option, if any.
		@@ -902,7 +976,8 @@ let
		else {};
		};

		/* Given a config set, expand mkMerge properties, and push down the
		/**
		Given a config set, expand mkMerge properties, and push down the
		other properties into the children. The result is a list of
		config sets that do not have properties at top-level. For
		example,
		@@ -916,6 +991,13 @@ let
		This transform is the critical step that allows mkIf conditions
		to refer to the full configuration without creating an infinite
		recursion.


		# Inputs

		`cfg`

		: 1\. Function argument
		*/
		pushDownProperties = cfg:
		if cfg._type or "" == "merge" then
		@@ -927,7 +1009,8 @@ let
		else # FIXME: handle mkOrder?
		[ cfg ];

		/* Given a config value, expand mkMerge properties, and discharge
		/**
		Given a config value, expand mkMerge properties, and discharge
		any mkIf conditions. That is, this is the place where mkIf
		conditions are actually evaluated. The result is a list of
		config values. For example, ‘mkIf false x’ yields ‘[]’,
		@@ -936,6 +1019,13 @@ let
		mkMerge [ 1 (mkIf true 2) (mkIf true (mkIf false 3)) ]

		yields ‘[ 1 2 ]’.


		# Inputs

		`def`

		: 1\. Function argument
		*/
		dischargeProperties = def:
		if def._type or "" == "merge" then
		@@ -951,7 +1041,8 @@ let
		else
		[ def ];

		/* Given a list of config values, process the mkOverride properties,
		/**
		Given a list of config values, process the mkOverride properties,
		that is, return the values that have the highest (that is,
		numerically lowest) priority, and strip the mkOverride
		properties. For example,
		@@ -969,6 +1060,13 @@ let
		]

		Note that "z" has the default priority 100.


		# Inputs

		`defs`

		: 1\. Function argument
		*/
		filterOverrides = defs: (filterOverrides' defs).values;

		@@ -982,9 +1080,18 @@ let
		inherit highestPrio;
		};

		/* Sort a list of properties. The sort priority of a property is
		/**
		Sort a list of properties. The sort priority of a property is
		defaultOrderPriority by default, but can be overridden by wrapping the property
		using mkOrder. */
		using mkOrder.


		# Inputs

		`defs`

		: 1\. Function argument
		*/
		sortProperties = defs:
		let
		strip = def:
		@@ -1004,14 +1111,24 @@ let
		else opt // { type = opt.type.substSubModules opt.options; options = []; };


		/*
		/**
		Merge an option's definitions in a way that preserves the priority of the
		individual attributes in the option value.

		This does not account for all option semantics, such as readOnly.

		Type:

		# Inputs

		`opt`

		: 1\. Function argument

		# Type

		```
		option -> attrsOf { highestPrio, value }
		```
		*/
		mergeAttrDefinitionsWithPrio = opt:
		let
		@@ -1038,7 +1155,20 @@ let
		})
		defsByAttr;

		/* Properties. */
		/**
		Properties.


		# Inputs

		`condition`

		: 1\. Function argument

		`content`

		: 2\. Function argument
		*/

		mkIf = condition: content:
		{ _type = "if";
		@@ -1116,11 +1246,25 @@ let
		mkAliasIfDef = option:
		mkIf (isOption option && option.isDefined);

		/* Compatibility. */
		/**
		Compatibility.


		# Inputs

		`modules`

		: 1\. Function argument

		`args`

		: 2\. Function argument
		*/
		fixMergeModules = modules: args: evalModules { inherit modules args; check = false; };


		/* Return a module that causes a warning to be shown if the
		/**
		Return a module that causes a warning to be shown if the
		specified option is defined. For example,

		mkRemovedOptionModule [ "boot" "loader" "grub" "bootDevice" ] "<replacement instructions>"
		@@ -1131,6 +1275,17 @@ let
		how to achieve the same functionality without the removed option,
		or alternatively a reasoning why the functionality is not needed.
		replacementInstructions SHOULD be provided!


		# Inputs

		`optionName`

		: 1\. Function argument

		`replacementInstructions`

		: 2\. Function argument
		*/
		mkRemovedOptionModule = optionName: replacementInstructions:
		{ options, ... }:
		@@ -1148,7 +1303,8 @@ let
		}];
		};

		/* Return a module that causes a warning to be shown if the
		/**
		Return a module that causes a warning to be shown if the
		specified "from" option is defined; the defined value is however
		forwarded to the "to" option. This can be used to rename options
		while providing backward compatibility. For example,
		@@ -1160,6 +1316,17 @@ let

		This also copies over the priority from the aliased option to the
		non-aliased option.


		# Inputs

		`from`

		: 1\. Function argument

		`to`

		: 2\. Function argument
		*/
		mkRenamedOptionModule = from: to: doRename {
		inherit from to;
		@@ -1169,12 +1336,16 @@ let
		};

		mkRenamedOptionModuleWith = {
		/* Old option path as list of strings. */
		/**
		Old option path as list of strings.
		*/
		from,
		/* New option path as list of strings. */
		/**
		New option path as list of strings.
		*/
		to,

		/*
		/**
		Release number of the first release that contains the rename, ignoring backports.
		Set it to the upcoming release, matching the nixpkgs/.version file.
		*/
		@@ -1188,7 +1359,8 @@ let
		"Obsolete option `${showOption from}' is used. It was renamed to `${showOption to}'.";
		};

		/* Return a module that causes a warning to be shown if any of the "from"
		/**
		Return a module that causes a warning to be shown if any of the "from"
		option is defined; the defined values can be used in the "mergeFn" to set
		the "to" value.
		This function can be used to merge multiple options into one that has a
		@@ -1215,6 +1387,21 @@ let

		This show a warning if any a.b.c or d.e.f is set, and set the value of
		x.y.z to the result of the merge function


		# Inputs

		`from`

		: 1\. Function argument

		`to`

		: 2\. Function argument

		`mergeFn`

		: 3\. Function argument
		*/
		mkMergedOptionModule = from: to: mergeFn:
		{ config, options, ... }:
		@@ -1240,7 +1427,8 @@ let
		(mergeFn config)));
		};

		/* Single "from" version of mkMergedOptionModule.
		/**
		Single "from" version of mkMergedOptionModule.
		Return a module that causes a warning to be shown if the "from" option is
		defined; the defined value can be used in the "mergeFn" to set the "to"
		value.
		@@ -1262,11 +1450,39 @@ let

		This show a warning if a.b.c is set, and set the value of x.y.z to the
		result of the change function


		# Inputs

		`from`

		: 1\. Function argument

		`to`

		: 2\. Function argument

		`changeFn`

		: 3\. Function argument
		*/
		mkChangedOptionModule = from: to: changeFn:
		mkMergedOptionModule [ from ] to changeFn;

		/* Like ‘mkRenamedOptionModule’, but doesn't show a warning. */
		/**
		Like ‘mkRenamedOptionModule’, but doesn't show a warning.


		# Inputs

		`from`

		: 1\. Function argument

		`to`

		: 2\. Function argument
		*/
		mkAliasOptionModule = from: to: doRename {
		inherit from to;
		visible = true;
		@@ -1274,13 +1490,15 @@ let
		use = id;
		};

		/* Transitional version of mkAliasOptionModule that uses MD docs.
		/**
		Transitional version of mkAliasOptionModule that uses MD docs.

		This function is no longer necessary and merely an alias of `mkAliasOptionModule`.
		*/
		mkAliasOptionModuleMD = mkAliasOptionModule;

		/* mkDerivedConfig : Option a -> (a -> Definition b) -> Definition b
		/**
		mkDerivedConfig : Option a -> (a -> Definition b) -> Definition b

		Create config definitions with the same priority as the definition of another option.
		This should be used for option definitions where one option sets the value of another as a convenience.
		@@ -1288,6 +1506,17 @@ let
		value using `mkDerivedConfig options.text (pkgs.writeText "filename.conf")`.

		It takes care of setting the right priority using `mkOverride`.


		# Inputs

		`opt`

		: 1\. Function argument

		`f`

		: 2\. Function argument
		*/
		# TODO: make the module system error message include information about `opt` in
		# error messages about conflicts. E.g. introduce a variation of `mkOverride` which
		@@ -1300,7 +1529,7 @@ let
		(opt.highestPrio or defaultOverridePriority)
		(f opt.value);

		/*
		/**
		Return a module that help declares an option that has been renamed.
		When a value is defined for the old option, it is forwarded to the `to` option.
		*/
		@@ -1450,18 +1679,34 @@ let
		modulePath: staticArg:
		lib.setDefaultModuleLocation modulePath (import modulePath staticArg);

		/* Use this function to import a JSON file as NixOS configuration.
		/**
		Use this function to import a JSON file as NixOS configuration.

		modules.importJSON :: path -> attrs


		# Inputs

		`file`

		: 1\. Function argument
		*/
		importJSON = file: {
		_file = file;
		config = lib.importJSON file;
		};

		/* Use this function to import a TOML file as NixOS configuration.
		/**
		Use this function to import a TOML file as NixOS configuration.

		modules.importTOML :: path -> attrs


		# Inputs

		`file`

		: 1\. Function argument
		*/
		importTOML = file: {
		_file = file;

lib/network/internal.nix

+2 −2

Original line number	Diff line number	Diff line
		@@ -16,7 +16,7 @@ let

		inherit (lib.lists) last;

		/*
		/**
		IPv6 addresses are 128-bit identifiers. The preferred form is 'x:x:x:x:x:x:x:x',
		where the 'x's are one to four hexadecimal digits of the eight 16-bit pieces of
		the address. See RFC 4291.
		@@ -138,7 +138,7 @@ let
		parseIpv6FromString = addr: parseExpandedIpv6 (expandIpv6 addr);
		in
		{
		/*
		/**
		Internally, an IPv6 address is stored as a list of 16-bit integers with 8
		elements. Wherever you see `IPv6` in internal functions docs, it means that
		it is a list of integers produced by one of the internal parsers, such as