penkovsky_sa/cherrypick
1
0
Fork 0
mirror of https://github.com/pese-git/cherrypick.git synced 2026-01-23 21:13:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: update documentations

Browse Source
This commit is contained in:
Sergey Penkovsky
2025-05-23 08:21:11 +03:00
parent 0fd10488f3
commit ef49595627
6 changed files with 208 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
cherrypick_annotations/lib/src/instance.dart
View File

@@ -11,11 +11,12 @@
// limitations under the License.
//
/// An annotation to specify that a method or class provides a new instance
/// each time it is requested.
/// ENGLISH:
/// Annotation to specify that a new instance should be provided on each request.
///
/// This is typically used to indicate that the annotated binding should
/// not be a singleton and a new object is created for every injection.
/// Use the `@instance()` annotation for methods or classes in your DI module
/// to declare that the DI container must create a new object every time
/// the dependency is injected (i.e., no singleton behavior).
///
/// Example:
/// ```dart
@@ -35,6 +36,32 @@
/// }
/// }
/// ```
///
/// RUSSIAN (Русский):
/// Аннотация для создания нового экземпляра при каждом запросе.
///
/// Используйте `@instance()` для методов или классов в DI-модуле,
/// чтобы указать, что контейнер внедрения зависимостей должен создавать
/// новый объект при каждом обращении к зависимости (то есть, не синглтон).
///
/// Пример:
/// ```dart
/// @module()
/// abstract class AppModule extends Module {
/// @instance()
/// Foo foo() => Foo();
/// }
/// ```
///
/// Будет сгенерирован следующий код:
/// ```dart
/// final class $AppModule extends AppModule {
/// @override
/// void builder(Scope currentScope) {
/// bind<Foo>().toInstance(() => foo());
/// }
/// }
/// ```
// ignore: camel_case_types
final class instance {
const instance();

42
cherrypick_annotations/lib/src/module.dart
View File

@@ -11,25 +11,57 @@
// limitations under the License.
//
/// An annotation used to mark a Dart class or library as a module.
/// ENGLISH:
/// Annotation for marking Dart classes or libraries as modules.
///
/// This annotation can be used for tooling, code generation,
/// or to provide additional metadata about the module.
/// Use the `@module()` annotation on abstract classes (or on a library)
/// to indicate that the class represents a DI (Dependency Injection) module.
/// This is commonly used in code generation tools to automatically register
/// and configure dependencies defined within the module.
///
/// Example:
/// ```dart
/// @module()
/// abstract class AppModule extends Module {
/// // Dependency definitions go here.
/// }
/// ```
/// Сгенерирует код:
///
/// Generates code like:
/// ```dart
/// final class $AppModule extends AppModule {
/// @override
/// void builder(Scope currentScope) {
///
/// // Dependency registration...
/// }
/// }
/// ```
///
/// RUSSIAN (Русский):
/// Аннотация для пометки классов или библиотек Dart как модуля.
///
/// Используйте `@module()` для абстрактных классов (или библиотек), чтобы
/// показать, что класс реализует DI-модуль (Dependency Injection).
/// Обычно используется генераторами кода для автоматической регистрации
/// и конфигурирования зависимостей, определённых в модуле.
///
/// Пример:
/// ```dart
/// @module()
/// abstract class AppModule extends Module {
/// // Определения зависимостей
/// }
/// ```
///
/// Будет сгенерирован код:
/// ```dart
/// final class $AppModule extends AppModule {
/// @override
/// void builder(Scope currentScope) {
/// // Регистрация зависимостей...
/// }
/// }
/// ```
// ignore: camel_case_types
final class module {
/// Creates a [module] annotation.

45
cherrypick_annotations/lib/src/named.dart
View File

@@ -11,10 +11,13 @@
// limitations under the License.
//
/// An annotation to assign a name or identifier to a class, method, or other element.
/// ENGLISH:
/// Annotation to assign a name or identifier to a class, method, or other element.
///
/// This can be useful for code generation, dependency injection,
/// or providing metadata within a framework.
/// The `@named('value')` annotation allows you to specify a string name
/// for a dependency, factory, or injectable. This is useful for distinguishing
/// between multiple registrations of the same type in dependency injection,
/// code generation, and for providing human-readable metadata.
///
/// Example:
/// ```dart
@@ -25,7 +28,33 @@
/// }
/// ```
///
/// Сгенерирует код:
/// This will generate:
/// ```dart
/// final class $AppModule extends AppModule {
/// @override
/// void builder(Scope currentScope) {
/// bind<Dio>().toProvide(() => dio()).withName('dio').singleton();
/// }
/// }
/// ```
///
/// RUSSIAN (Русский):
/// Аннотация для задания имени или идентификатора классу, методу или другому элементу.
///
/// Аннотация `@named('значение')` позволяет указать строковое имя для зависимости,
/// фабрики или внедряемого значения. Это удобно для различения нескольких
/// регистраций одного типа в DI, генерации кода.
///
/// Пример:
/// ```dart
/// @module()
/// abstract class AppModule extends Module {
/// @named('dio')
/// Dio dio() => Dio();
/// }
/// ```
///
/// Будет сгенерирован следующий код:
/// ```dart
/// final class $AppModule extends AppModule {
/// @override
@@ -36,9 +65,13 @@
/// ```
// ignore: camel_case_types
final class named {
/// The assigned name or identifier.
/// EN: The assigned name or identifier for the element.
///
/// RU: Назначенное имя или идентификатор для элемента.
final String value;
/// Creates a [named] annotation with the given [value].
/// EN: Creates a [named] annotation with the given [value].
///
/// RU: Создаёт аннотацию [named] с заданным значением [value].
const named(this.value);
}

31
cherrypick_annotations/lib/src/params.dart
View File

@@ -11,11 +11,14 @@
// limitations under the License.
//
/// An annotation to indicate that a parameter is to be injected with run-time provided arguments.
/// ENGLISH:
/// Annotation to mark a method parameter for injection with run-time arguments.
///
/// Use this annotation to mark a method parameter that should receive arguments
/// passed during the resolution of a dependency (for example, through the
/// `.withParams(...)` method in the generated code).
/// Use the `@params()` annotation to specify that a particular parameter of a
/// provider method should be assigned a value supplied at resolution time,
/// rather than during static dependency graph creation. This is useful in DI
/// when a dependency must receive dynamic data passed by the consumer
/// (via `.withParams(...)` in the generated code).
///
/// Example:
/// ```dart
@@ -27,6 +30,26 @@
/// ```dart
/// bind<String>().toProvideWithParams((args) => greet(args));
/// ```
///
/// RUSSIAN (Русский):
/// Аннотация для пометки параметра метода, который будет внедряться со значением во время выполнения.
///
/// Используйте `@params()` чтобы указать, что конкретный параметр метода-провайдера
/// должен получать значение, передаваемое в момент обращения к зависимости,
/// а не на этапе построения графа зависимостей. Это полезно, если зависимость
/// должна получать данные динамически от пользователя или другого процесса
/// через `.withParams(...)` в сгенерированном коде.
///
/// Пример:
/// ```dart
/// @provide()
/// String greet(@params() dynamic params) => 'Hello $params';
/// ```
///
/// Будет сгенерировано:
/// ```dart
/// bind<String>().toProvideWithParams((args) => greet(args));
/// ```
// ignore: camel_case_types
final class params {
const params();

46
cherrypick_annotations/lib/src/provide.dart
View File

@@ -11,28 +11,56 @@
// limitations under the License.
//
/// An annotation to indicate that a method provides a dependency to the module.
/// ENGLISH:
/// Annotation to declare a factory/provider method or class as a singleton.
///
/// This annotation is typically used in conjunction with dependency injection,
/// marking methods whose return value should be registered as a provider.
/// The annotated method can optionally declare dependencies as parameters,
/// which will be resolved and injected automatically.
/// Use the `@singleton()` annotation on methods in your DI module to specify
/// that only one instance of the resulting object should be created and shared
/// for all consumers. This is especially useful in dependency injection
/// frameworks and service locators.
///
/// Example:
/// ```dart
/// @module()
/// abstract class AppModule extends Module {
/// @provide()
/// Foo foo(Bar bar) => Foo(bar);
/// @singleton()
/// Dio dio() => Dio();
/// }
/// ```
///
/// This will generate:
/// This generates the following code:
/// ```dart
/// final class $AppModule extends AppModule {
/// @override
/// void builder(Scope currentScope) {
/// bind<Foo>().toProvide(() => foo(currentScope.resolve<Bar>()));
/// bind<Dio>().toProvide(() => dio()).singleton();
/// }
/// }
/// ```
///
/// RUSSIAN (Русский):
/// Аннотация для объявления фабричного/провайдерного метода или класса синглтоном.
///
/// Используйте `@singleton()` для методов внутри DI-модуля, чтобы указать,
/// что соответствующий объект (экземпляр класса) должен быть создан только один раз
/// и использоваться всеми компонентами приложения (единый общий экземпляр).
/// Это характерно для систем внедрения зависимостей и сервис-локаторов.
///
/// Пример:
/// ```dart
/// @module()
/// abstract class AppModule extends Module {
/// @singleton()
/// Dio dio() => Dio();
/// }
/// ```
///
/// Будет сгенерирован следующий код:
/// ```dart
/// final class $AppModule extends AppModule {
/// @override
/// void builder(Scope currentScope) {
/// bind<Dio>().toProvide(() => dio()).singleton();
/// }
/// }
/// ```

42
cherrypick_annotations/lib/src/singleton.dart
View File

@@ -11,11 +11,14 @@
// limitations under the License.
//
/// An annotation to declare a class as a singleton.
/// ENGLISH:
/// Annotation to declare a dependency as a singleton.
///
/// This can be used to indicate that only one instance of the class
/// should be created, which is often useful in dependency injection
/// frameworks or service locators.
/// Use the `@singleton()` annotation on provider methods inside a module
/// to indicate that only a single instance of this dependency should be
/// created and shared throughout the application's lifecycle. This is
/// typically used in dependency injection frameworks or service locators
/// to guarantee a single shared instance.
///
/// Example:
/// ```dart
@@ -25,7 +28,36 @@
/// Dio dio() => Dio();
/// }
/// ```
/// Сгенерирует код:
///
/// This will generate code like:
/// ```dart
/// final class $AppModule extends AppModule {
/// @override
/// void builder(Scope currentScope) {
/// bind<Dio>().toProvide(() => dio()).singleton();
/// }
/// }
/// ```
///
/// RUSSIAN (Русский):
/// Аннотация для объявления зависимости как синглтона.
///
/// Используйте `@singleton()` для методов-провайдеров внутри модуля,
/// чтобы указать, что соответствующий объект должен быть создан
/// единожды и использоваться во всём приложении (общий синглтон).
/// Это характерно для систем внедрения зависимостей и сервис-локаторов,
/// чтобы гарантировать один общий экземпляр.
///
/// Пример:
/// ```dart
/// @module()
/// abstract class AppModule extends Module {
/// @singleton()
/// Dio dio() => Dio();
/// }
/// ```
///
/// Будет сгенерирован следующий код:
/// ```dart
/// final class $AppModule extends AppModule {
/// @override