[hooks] Document user-defines in API

[dcharkes]

No description provided.

[github-actions]

Package publishing

Package	Version	Status	Publish tag (post-merge)
package:code_assets	1.2.1	already published at pub.dev
package:data_assets	0.20.0	already published at pub.dev
package:ffi	2.2.0	already published at pub.dev
package:hooks	2.0.2	ready to publish	hooks-v2.0.2
package:hooks_runner	1.4.0	already published at pub.dev
package:jni_flutter	1.0.1	already published at pub.dev
package:native_toolchain_c	0.19.1	already published at pub.dev
package:record_use	0.6.1-wip	WIP (no publish necessary)
package:swift2objc	0.2.0	already published at pub.dev
package:swiftgen	0.1.3	ready to publish	swiftgen-v0.1.3

Documentation at https://github.com/dart-lang/ecosystem/wiki/Publishing-automation.

[github-actions]

PR Health

API leaks ✔️

The following packages contain symbols visible in the public API, but not exported by the library. Export these symbols or remove them from your publicly visible API.

Package	Leaked API symbol	Leaking sources

This check can be disabled by tagging the PR with skip-leaking-check.

Changelog Entry ✔️

Package	Changed Files

Changes to files need to be accounted for in their respective changelogs.

This check can be disabled by tagging the PR with skip-changelog-check.

Breaking changes ✔️

Package	Change	Current Version	New Version	Needed Version	Looking good?
hooks	None	2.0.1	2.0.2	2.0.1	✔️

This check can be disabled by tagging the PR with skip-breaking-check.

[dcharkes]

(CI redness fix: #3408)

[jonasfj]

flip this around, the assumption starts with users are not in a workspace.

[jonasfj]

This should be documented in:
https://dart.dev/tools/pub/pubspec

[dcharkes]

dart-lang/site-www#7323

[jonasfj]

Suggested change

	/// my_database:
	/// my_package:

[jonasfj]

Suggested change

	/// <!-- file://./../../example/api/config_snippet_6.dart -->
	/// ```dart
	/// import 'dart:io';
	/// import 'package:hooks/hooks.dart';
	///
	/// void main(List<String> args) async {
	/// await build(args, (input, output) async {
	/// // Access raw user-defines value
	/// final debugLogging =
	/// input.userDefines['enable_debug_logging'] == true;
	/// if (debugLogging) {
	/// print('Debug logging is enabled.');
	/// }
	///
	/// // Resolve relative path against pubspec.yaml base path
	/// final customAssetUri = input.userDefines.path('custom_asset');
	/// if (customAssetUri != null) {
	/// final file = File.fromUri(customAssetUri);
	/// output.dependencies.add(file.uri); // Declare cache dependency
	/// // Use the file...
	/// }
	/// });
	/// }
	/// ```
	/// {@example /example/api/config_snippet_6.dart}

Analyzer might still complain 🙈 , but it should work in dartdoc

[dcharkes]

I'll look into adopting the new {@example later, my current script works.

[jonasfj]

YAML can have circular references, are you sure you want to say YAML?

I think that you should consider running user-defines through json.decode(json.encode()) unless you want package:yaml to accidentally be part of the public API here.

For the record, if done right having package:yaml as part the public API can be cool, because each YamlNode probably has a SourceSpan that makes printing errors really cool.

But also I'm guessing this travels over some serialized protocol so it might already be JSON proper

[jonasfj]

Suggested change

	// Access raw user-defines value
	final debugLogging =
	input.userDefines['enable_debug_logging'] == true;
	if (debugLogging) {
	print('Debug logging is enabled.');
	}
	// Access raw user-defines value
	final debugLogging =
	input.userDefines['enable_debug_logging'];
	// Validate input!
	if (debugLogging is! bool?) {
	throw DacoMightKnowWhatErrorOrExceptionIAmSupposedToThrow('hooks.user_defines.my_package.enable_debug_logging must be a boolean (or omitted)');
	}
	if (debugLogging == true) {
	print('Debug logging is enabled.');
	}

[dcharkes]

any exception will do