From 90d1279289f01379f84d0de530218a508fbc2ad2 Mon Sep 17 00:00:00 2001 From: Nikolas Rimikis Date: Mon, 30 Oct 2023 19:57:35 +0100 Subject: [PATCH 1/2] chore: test for dart doc errors Signed-off-by: Nikolas Rimikis --- .cspell/tools.txt | 2 ++ dartdoc_options.yaml | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 dartdoc_options.yaml diff --git a/.cspell/tools.txt b/.cspell/tools.txt index 8a6f2600..748b8456 100644 --- a/.cspell/tools.txt +++ b/.cspell/tools.txt @@ -10,6 +10,7 @@ classpath cloc commitlint dapplication +dartdoc dists dockerenv endforeach @@ -43,6 +44,7 @@ libindicator libsqlite mipmap ndebug +nodoc nproc openrelay openrelayprojectsecret diff --git a/dartdoc_options.yaml b/dartdoc_options.yaml new file mode 100644 index 00000000..a2964ddf --- /dev/null +++ b/dartdoc_options.yaml @@ -0,0 +1,35 @@ +include: package:neon_lints/dartdoc_options.yaml + +dartdoc: + nodoc: ['lib/l10n/*.dart'] + showUndocumentedCategories: true + ignore: + ## Errors that are ignored: + ## Warnings that are ignored: + - reexported-private-api-across-packages + ## Default ignores for dartdoc: + errors: + ## Default errors of dartdoc: + - duplicate-file + - invalid-parameter + - tool-error + - unresolved-export + ## Warnings that are elevated to errors: + - ambiguous-doc-reference + - ambiguous-reexport + - broken-link + - category-order-gives-missing-package-name + - deprecated + - ignored-canonical-for + - missing-from-search-index + - no-canonical-found + - no-documentable-libraries + - no-library-level-docs + - orphaned-file + - unknown-file + - unknown-macro + - unresolved-doc-reference + ## Ignores that are elevated to errors: + # - type-as-html # broken, https://github.com/dart-lang/dartdoc/issues/3545 + - missing-constant-constructor + - missing-code-block-language From 34957f18392dcc8c85689bdb46d113be421ab5c8 Mon Sep 17 00:00:00 2001 From: Nikolas Rimikis Date: Mon, 30 Oct 2023 19:58:33 +0100 Subject: [PATCH 2/2] fix: fix various documentation errors Signed-off-by: Nikolas Rimikis --- packages/dynamite/dynamite/lib/dynamite.dart | 9 ++++++- packages/neon/neon/lib/models.dart | 11 ++++++++ .../lib/src/models/app_implementation.dart | 2 +- packages/neon/neon/lib/src/widgets/image.dart | 4 ++- packages/neon/neon_dashboard/lib/src/app.dart | 26 +++++++++++++++++++ packages/neon/neon_files/lib/neon_files.dart | 26 ++++++++++++++++++- packages/neon/neon_files/lib/utils/task.dart | 2 +- packages/neon/neon_news/lib/neon_news.dart | 26 ++++++++++++++++++- packages/neon/neon_notes/lib/neon_notes.dart | 24 +++++++++++++++++ .../lib/neon_notifications.dart | 24 +++++++++++++++++ .../nextcloud/lib/src/helpers/spreed.dart | 4 +-- 11 files changed, 150 insertions(+), 8 deletions(-) diff --git a/packages/dynamite/dynamite/lib/dynamite.dart b/packages/dynamite/dynamite/lib/dynamite.dart index f8fd102e..709b4d9c 100644 --- a/packages/dynamite/dynamite/lib/dynamite.dart +++ b/packages/dynamite/dynamite/lib/dynamite.dart @@ -1,4 +1,11 @@ -// ignore: unnecessary_library_directive +/// Configuration for using `package:build`-compatible build systems. +/// +/// See: +/// * [build_runner](https://pub.dev/packages/build_runner) +/// +/// This library is **not** intended to be imported by typical end-users unless +/// you are creating a custom compilation pipeline. See documentation for +/// details, and `build.yaml` for how these builders are configured by default. library dynamite; export 'src/openapi_builder.dart'; diff --git a/packages/neon/neon/lib/models.dart b/packages/neon/neon/lib/models.dart index f9ac5fc2..34adeabf 100644 --- a/packages/neon/neon/lib/models.dart +++ b/packages/neon/neon/lib/models.dart @@ -1,3 +1,14 @@ +/// The Neon model definitions. +/// +/// To use, import `import 'package:neon/models.dart';`. +/// +/// This library provides basic data models and interfaces to build a neon +/// client. +/// +/// {@canonicalFor label_builder.LabelBuilder} +library models; + export 'package:neon/src/models/account.dart' hide Credentials, LoginQRcode; export 'package:neon/src/models/app_implementation.dart'; +export 'package:neon/src/models/label_builder.dart'; export 'package:neon/src/models/notifications_interface.dart'; diff --git a/packages/neon/neon/lib/src/models/app_implementation.dart b/packages/neon/neon/lib/src/models/app_implementation.dart index 9ba66fd7..b70cffa1 100644 --- a/packages/neon/neon/lib/src/models/app_implementation.dart +++ b/packages/neon/neon/lib/src/models/app_implementation.dart @@ -34,7 +34,7 @@ abstract class AppImplementation /// {@macro flutter.widgets.widgetsApp.localizationsDelegates} LocalizationsDelegate get localizationsDelegate; - /// {@macro flutter.widgets.widgetsApp.supportedLocales} + /// The list of locales that this app has been localized for. Iterable get supportedLocales; /// Default localized app name used in [name]. diff --git a/packages/neon/neon/lib/src/widgets/image.dart b/packages/neon/neon/lib/src/widgets/image.dart index 74878ed0..da733f1e 100644 --- a/packages/neon/neon/lib/src/widgets/image.dart +++ b/packages/neon/neon/lib/src/widgets/image.dart @@ -420,7 +420,9 @@ class NeonImageWrapper extends StatelessWidget { /// /// If null defaults to `const BorderRadius.all(Radius.circular(8))`. /// - /// {@macro flutter.painting.BoxDecoration.clip} + /// The shape or the [borderRadius] won't clip the children of the decorated [Container]. + /// If the clip is required, insert a clip widget (e.g., [ClipRect], [ClipRRect], [ClipPath]) + /// as the child of the [Container]. Be aware that clipping may be costly in terms of performance. final BorderRadius? borderRadius; @override diff --git a/packages/neon/neon_dashboard/lib/src/app.dart b/packages/neon/neon_dashboard/lib/src/app.dart index 9c4f5f38..4d3a15f4 100644 --- a/packages/neon/neon_dashboard/lib/src/app.dart +++ b/packages/neon/neon_dashboard/lib/src/app.dart @@ -1,3 +1,29 @@ +/// The Neon client for the dashboard app. +/// +/// Add `DashboardApp()` to your runNeon command to execute this app. +/// +/// A basic implementation could look like: +///```dart +///Future main() async { +/// await runNeon( +/// appImplementations: { +/// DashboardApp() +/// }, +/// theme: NeonTheme( +/// branding: Branding( +/// name: 'Dashboard', +/// logo: VectorGraphic( +/// loader: AssetBytesLoader( +/// 'assets/logo.svg.vec', +/// ), +/// ), +/// ), +/// ), +/// ); +/// } +///``` +library dashboard; + import 'package:flutter/material.dart'; import 'package:go_router/go_router.dart'; import 'package:neon/models.dart'; diff --git a/packages/neon/neon_files/lib/neon_files.dart b/packages/neon/neon_files/lib/neon_files.dart index 6942c5ac..31882f28 100644 --- a/packages/neon/neon_files/lib/neon_files.dart +++ b/packages/neon/neon_files/lib/neon_files.dart @@ -1,4 +1,28 @@ -library neon_files; +/// The Neon client for the files app. +/// +/// Add `FilesApp()` to your runNeon command to execute this app. +/// +/// A basic implementation could look like: +///```dart +///Future main() async { +/// await runNeon( +/// appImplementations: { +/// FilesApp() +/// }, +/// theme: NeonTheme( +/// branding: Branding( +/// name: 'Files', +/// logo: VectorGraphic( +/// loader: AssetBytesLoader( +/// 'assets/logo.svg.vec', +/// ), +/// ), +/// ), +/// ), +/// ); +/// } +///``` +library files; import 'dart:async'; diff --git a/packages/neon/neon_files/lib/utils/task.dart b/packages/neon/neon_files/lib/utils/task.dart index 4d3c9fcc..f4324237 100644 --- a/packages/neon/neon_files/lib/utils/task.dart +++ b/packages/neon/neon_files/lib/utils/task.dart @@ -13,7 +13,7 @@ sealed class FilesTask { @protected final streamController = StreamController(); - /// Task progress in percent [0, 1]. + /// Task progress in percent `[0, 1]`. late final progress = streamController.stream.asBroadcastStream(); } diff --git a/packages/neon/neon_news/lib/neon_news.dart b/packages/neon/neon_news/lib/neon_news.dart index 81fef6e0..53bb272a 100644 --- a/packages/neon/neon_news/lib/neon_news.dart +++ b/packages/neon/neon_news/lib/neon_news.dart @@ -1,4 +1,28 @@ -library neon_news; +/// The Neon client for the news app. +/// +/// Add `NewsApp()` to your runNeon command to execute this app. +/// +/// A basic implementation could look like: +///```dart +///Future main() async { +/// await runNeon( +/// appImplementations: { +/// NewsApp() +/// }, +/// theme: NeonTheme( +/// branding: Branding( +/// name: 'News', +/// logo: VectorGraphic( +/// loader: AssetBytesLoader( +/// 'assets/logo.svg.vec', +/// ), +/// ), +/// ), +/// ), +/// ); +/// } +///``` +library news; import 'dart:async'; diff --git a/packages/neon/neon_notes/lib/neon_notes.dart b/packages/neon/neon_notes/lib/neon_notes.dart index d0a1d314..4ca927e8 100644 --- a/packages/neon/neon_notes/lib/neon_notes.dart +++ b/packages/neon/neon_notes/lib/neon_notes.dart @@ -1,3 +1,27 @@ +/// The Neon client for the notes app. +/// +/// Add `NotesApp()` to your runNeon command to execute this app. +/// +/// A basic implementation could look like: +///```dart +///Future main() async { +/// await runNeon( +/// appImplementations: { +/// NotesApp() +/// }, +/// theme: NeonTheme( +/// branding: Branding( +/// name: 'Notes', +/// logo: VectorGraphic( +/// loader: AssetBytesLoader( +/// 'assets/logo.svg.vec', +/// ), +/// ), +/// ), +/// ), +/// ); +/// } +///``` library notes; import 'dart:async'; diff --git a/packages/neon/neon_notifications/lib/neon_notifications.dart b/packages/neon/neon_notifications/lib/neon_notifications.dart index 89dbaec0..85f20a38 100644 --- a/packages/neon/neon_notifications/lib/neon_notifications.dart +++ b/packages/neon/neon_notifications/lib/neon_notifications.dart @@ -1,3 +1,27 @@ +/// The Neon client for the notifications app. +/// +/// Add `NotificationsApp()` to your runNeon command to execute this app. +/// +/// A basic implementation could look like: +///```dart +///Future main() async { +/// await runNeon( +/// appImplementations: { +/// NotificationsApp() +/// }, +/// theme: NeonTheme( +/// branding: Branding( +/// name: 'Notifications', +/// logo: VectorGraphic( +/// loader: AssetBytesLoader( +/// 'assets/logo.svg.vec', +/// ), +/// ), +/// ), +/// ), +/// ); +/// } +///``` library notifications; import 'dart:async'; diff --git a/packages/nextcloud/lib/src/helpers/spreed.dart b/packages/nextcloud/lib/src/helpers/spreed.dart index 1b00eb30..5cba730c 100644 --- a/packages/nextcloud/lib/src/helpers/spreed.dart +++ b/packages/nextcloud/lib/src/helpers/spreed.dart @@ -49,7 +49,7 @@ enum RoomType { /// Types of chat messages. /// -/// Use [name] to get the string representation that is used in the API. +/// Use `name` to get the string representation that is used in the API. /// See https://github.com/nextcloud/spreed/blob/master/lib/Chat/ChatManager.php. enum MessageType { /// Message. @@ -79,7 +79,7 @@ enum MessageType { /// Actor types of chat messages. /// -/// Use [name] to get the string representation that is used in the API. +/// Use `name` to get the string representation that is used in the API. /// See https://github.com/nextcloud/spreed/blob/master/lib/Model/Attendee.php. enum ActorType { /// Logged-in users.