From 5fe8d84cf67e245d91454888e68986cc6b627846 Mon Sep 17 00:00:00 2001 From: Hugo Pointcheval Date: Thu, 13 Apr 2023 22:01:56 +0200 Subject: [PATCH] docs(component_copy_with): add some documentation --- .../README.md | 50 ++++++++++++------- .../analysis_options.yaml | 2 +- .../src/component_copy_with_extension.dart | 24 ++++++++- .../lib/src/component_proxy_extension.dart | 32 +++++++++--- .../lib/src/domain/component_annotation.dart | 4 ++ .../pubspec.yaml | 7 +-- .../wyatt_component_copy_with_gen/README.md | 24 +++++---- .../pubspec.yaml | 8 ++- 8 files changed, 104 insertions(+), 47 deletions(-) diff --git a/packages/wyatt_component_copy_with_extension/README.md b/packages/wyatt_component_copy_with_extension/README.md index 3ef1d24d..4dd5beaf 100644 --- a/packages/wyatt_component_copy_with_extension/README.md +++ b/packages/wyatt_component_copy_with_extension/README.md @@ -7,7 +7,7 @@ * the Free Software Foundation, either version 3 of the License, or * any later version. * - * This program is distributed in the hope that it will be useful, + * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. @@ -16,15 +16,32 @@ * along with this program. If not, see . --> -# Flutter - Component Copy With Extension +# Component Copy With Extension

Style: Wyatt Analysis - SDK: Flutter + SDK: Dart & Flutter

This package provides annotations for generating code and simplifying the use of an UI kit within a Flutter application. **The package contains only the annotation classes**. +> This package does not contain Flutter specific code, but there is no sense in using it without Flutter. + +## Summary + +* `ComponentProxyExtension` - Annotation class for generating a proxy of a component of an UI kit. +* `ComponentCopyWithExtension` - Annotation class for generating the copyWith method of a component implementation. + +For example, let's say we have a component of an UI kit that we want to use in our application. + +1) We create the component in the `wyatt_ui_components` , add the `ComponentProxyExtension` annotation and generate the code. This component does not have any specific implementation, and only have a set of properties. +2) Now we implement the component in our ui kit, `wyatt_ui_kit` , add the `ComponentCopyWithExtension` annotation and generate the code. This component has a specific implementation and can be used in the application. +3) But we can implement multiple ui kits, and each of them can have their own implementation of the same component. And at the top of the application tree we can use the `wyatt_ui_components` package, which contains only the proxy of the component. + +> In that way, the **application is UI kit agnostic**, and we can easily change the UI kit without changing the code of the application. + +We will use the `LoaderComponent` component as an example in this documentation. + ## Annotation Classes #### `ComponentProxyExtension` @@ -32,31 +49,30 @@ This package provides annotations for generating code and simplifying the use of This annotation class is used to annotate a new component of an UI kit in the `wyatt_ui_components` package. It generates the abstract proxy of the component and allows access to all its properties in different packages and throughout the application. ```dart -part 'text_field_component.g.dart'; +part 'loader_component.g.dart'; @ComponentProxyExtension() -abstract class TextFieldComponent extends Component { - with CopyWithMixin<$TextFieldComponentCWProxy> { - - const TextFieldComponent({ - ... +abstract class LoaderComponent extends Component + with CopyWithMixin<$LoaderComponentCWProxy> { + + const LoaderComponent({ + ... }); } ``` #### `ComponentCopyWithExtension` -This annotation class is used to annotate the implementation of components directly in the application. It generates the implementation of the proxy and the mixin to ensure that the component meets the specifications defined in the `wyatt_ui_components package`. +This annotation class is used to annotate the implementation of components directly in the application. It generates the implementation of the proxy and the mixin to ensure that the component meets the specifications defined in the `wyatt_ui_components package` . ```dart -part 'text_field_component.g.dart'; +part 'loader.g.dart'; -@ComponentProxyExtension() -abstract class TextFieldComponent extends Component { - with CopyWithMixin<$TextFieldComponentCWProxy> { - - const TextFieldComponent({ - ... +@ComponentCopyWithExtension() +class Loader extends LoaderComponent with $LoaderCWMixin { + + const Loader({ + ... }); } ``` diff --git a/packages/wyatt_component_copy_with_extension/analysis_options.yaml b/packages/wyatt_component_copy_with_extension/analysis_options.yaml index 0939257e..1c320a71 100644 --- a/packages/wyatt_component_copy_with_extension/analysis_options.yaml +++ b/packages/wyatt_component_copy_with_extension/analysis_options.yaml @@ -1,5 +1,5 @@ -include: package:wyatt_analysis/analysis_options.flutter.yaml +include: package:wyatt_analysis/analysis_options.yaml diff --git a/packages/wyatt_component_copy_with_extension/lib/src/component_copy_with_extension.dart b/packages/wyatt_component_copy_with_extension/lib/src/component_copy_with_extension.dart index 482b1748..a71e23bf 100644 --- a/packages/wyatt_component_copy_with_extension/lib/src/component_copy_with_extension.dart +++ b/packages/wyatt_component_copy_with_extension/lib/src/component_copy_with_extension.dart @@ -17,9 +17,29 @@ import 'package:meta/meta_meta.dart'; import 'package:wyatt_component_copy_with_extension/component_copy_with_extension.dart'; -/// Annotation used to indicate that the `copyWith` extension -/// should be generated for the compononent. +/// {@template component_copy_with_extension} +/// This annotation class is used to annotate the implementation of components +/// directly in the application. It generates the implementation of the proxy +/// and the mixin to ensure that the component meets the specifications +/// defined in the UI Kit. +/// +/// Basically it indicate that the `copyWith` extension +/// should be generated for the component. +/// +/// ```dart +/// part 'loader.g.dart'; +/// +/// @ComponentCopyWithExtension() +/// class Loader extends LoaderComponent with $LoaderCWMixin { +/// +/// const Loader({ +/// ... +/// }); +/// } +/// ``` +/// {@endtemplate} @Target({TargetKind.classType}) class ComponentCopyWithExtension extends ComponentAnnotation { + /// {@macro component_copy_with_extension} const ComponentCopyWithExtension({super.skipFields}); } diff --git a/packages/wyatt_component_copy_with_extension/lib/src/component_proxy_extension.dart b/packages/wyatt_component_copy_with_extension/lib/src/component_proxy_extension.dart index 3e75eef5..d34ac82c 100644 --- a/packages/wyatt_component_copy_with_extension/lib/src/component_proxy_extension.dart +++ b/packages/wyatt_component_copy_with_extension/lib/src/component_proxy_extension.dart @@ -14,12 +14,32 @@ // along with this program. If not, see . import 'package:meta/meta_meta.dart'; +import 'package:wyatt_component_copy_with_extension/src/domain/component_annotation.dart'; +/// {@template component_proxy_extension} +/// This annotation class is used to annotate a new component of an UI kit. +/// It generates the abstract proxy of the component and allows access to +/// all its properties in different packages and throughout the application. +/// +/// ```dart +/// part 'loader_component.g.dart'; +/// +/// @ComponentProxyExtension() +/// abstract class LoaderComponent extends Component +/// with CopyWithMixin<$LoaderComponentCWProxy> { +/// +/// const LoaderComponent({ +/// ... +/// }); +/// } +/// ``` +/// +/// The [skipFields] option allows you to directly and specifically change +/// a field. This makes it easier to use. +/// +/// {@endtemplate} @Target({TargetKind.classType}) -class ComponentProxyExtension { - const ComponentProxyExtension({ - this.skipFields = true, - }); - - final bool? skipFields; +class ComponentProxyExtension extends ComponentAnnotation { + /// {@macro component_proxy_extension} + const ComponentProxyExtension({super.skipFields}); } diff --git a/packages/wyatt_component_copy_with_extension/lib/src/domain/component_annotation.dart b/packages/wyatt_component_copy_with_extension/lib/src/domain/component_annotation.dart index 1faf6119..4408aa19 100644 --- a/packages/wyatt_component_copy_with_extension/lib/src/domain/component_annotation.dart +++ b/packages/wyatt_component_copy_with_extension/lib/src/domain/component_annotation.dart @@ -14,7 +14,11 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +/// {@template component_annotation} +/// Abstract class that is used as a base for all annotations +/// {@endtemplate} abstract class ComponentAnnotation { + /// {@macro component_annotation} const ComponentAnnotation({this.skipFields = true}); /// Prevent the library from generating `copyWith` functions for individual diff --git a/packages/wyatt_component_copy_with_extension/pubspec.yaml b/packages/wyatt_component_copy_with_extension/pubspec.yaml index de13dc2d..4b0375c5 100644 --- a/packages/wyatt_component_copy_with_extension/pubspec.yaml +++ b/packages/wyatt_component_copy_with_extension/pubspec.yaml @@ -3,18 +3,15 @@ description: Extension for component copy with feature. repository: https://git.wyatt-studio.fr/Wyatt-FOSS/wyatt-packages/src/branch/master/packages/component_copy_with_extension version: 1.0.0 +publish_to: https://git.wyatt-studio.fr/api/packages/Wyatt-FOSS/pub + environment: sdk: ">=2.19.0 <3.0.0" dependencies: meta: ^1.8.0 - path: ^1.8.0 dev_dependencies: wyatt_analysis: hosted: https://git.wyatt-studio.fr/api/packages/Wyatt-FOSS/pub version: ^2.4.1 - -# The following section is specific to Flutter. -flutter: - uses-material-design: true diff --git a/packages/wyatt_component_copy_with_gen/README.md b/packages/wyatt_component_copy_with_gen/README.md index 6b606cd8..64e5e799 100644 --- a/packages/wyatt_component_copy_with_gen/README.md +++ b/packages/wyatt_component_copy_with_gen/README.md @@ -7,7 +7,7 @@ * the Free Software Foundation, either version 3 of the License, or * any later version. * - * This program is distributed in the hope that it will be useful, + * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. @@ -16,30 +16,32 @@ * along with this program. If not, see . --> -# Dart - Component Copy With Gen +# Component Copy With Gen

Style: Wyatt Analysis SDK: Dart & Flutter

-A Dart package for generating code from annotations to ease the use of a UIKit in Flutter applications. The generated code is based on the annotation classes present in the 'wyatt_component_copy_with_extension' package. +A Dart package for generating code from annotations to ease the use of a UIKit in Flutter applications. The generated code is based on the annotation classes present in the [ `wyatt_component_copy_with_extension` package](https://git.wyatt-studio.fr/Wyatt-FOSS/wyatt-packages/src/branch/master/packages/wyatt_component_copy_with_extension) + +> This package does not contain Flutter specific code, but there is no sense in using it without Flutter. ## Features -- Supports the generation of abstract proxies in the `wyatt_ui_components` package. -- Supports direct use in Flutter applications. +* Supports the generation of abstract proxies in the `wyatt_ui_components` package. +* Supports direct use in Flutter applications. ## Usage ### In the 'wyatt_ui_components' package -- Add the appropriate annotation when addicdng a new component. -- Run the build runner command to generate the proxy. +* Add the appropriate annotation when adding a new component. +* Run the build runner command to generate the proxy. -### In Flutter applications +### In Flutter applications (or UI Kit implementations) -- Add the following dependencies to your pubspec.yaml: +* Add the following dependencies to your pubspec.yaml: ```yaml dependencies: @@ -51,7 +53,7 @@ dev_dependencies: build_runner: ^2.3.3 ``` -- In your UIKit, extend the desired component class and add the appropriate annotation. -- Run the code generation command via the build runner. +* In your UIKit, extend the desired component class and add the appropriate annotation. +* Run the code generation command via the build runner. For further details and additional features on class annotation, see the 'wyatt_component_copy_with_extension' package's README. diff --git a/packages/wyatt_component_copy_with_gen/pubspec.yaml b/packages/wyatt_component_copy_with_gen/pubspec.yaml index bae83cb0..301cb28c 100644 --- a/packages/wyatt_component_copy_with_gen/pubspec.yaml +++ b/packages/wyatt_component_copy_with_gen/pubspec.yaml @@ -3,21 +3,19 @@ description: Generator for copywith method for components. repository: https://git.wyatt-studio.fr/Wyatt-FOSS/wyatt-packages/src/branch/master/packages/component_copy_with_gen version: 1.0.0 -publish_to: "none" +publish_to: https://git.wyatt-studio.fr/api/packages/Wyatt-FOSS/pub environment: sdk: ">=2.19.0 <3.0.0" dependencies: - path: ^1.8.0 build: ^2.3.1 source_gen: ^1.2.7 analyzer: ^5.4.0 wyatt_component_copy_with_extension: - git: - url: ssh://git@git.wyatt-studio.fr:993/Wyatt-FOSS/wyatt-packages.git - path: packages/wyatt_component_copy_with_extension + hosted: https://git.wyatt-studio.fr/api/packages/Wyatt-FOSS/pub + version: ^1.0.0 dev_dependencies: test: ^1.21.0