Merge pull request #1062 from nextcloud/docs/lint_dartdoc_errors

.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

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

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';

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';

packages/neon/neon/lib/src/models/app_implementation.dart

@@ -34,7 +34,7 @@ abstract class AppImplementation<T extends Bloc, R extends NextcloudAppOptions>
   /// {@macro flutter.widgets.widgetsApp.localizationsDelegates}
   LocalizationsDelegate<Object> get localizationsDelegate;
 
-  /// {@macro flutter.widgets.widgetsApp.supportedLocales}
+  /// The list of locales that this app has been localized for.
   Iterable<Locale> get supportedLocales;
 
   /// Default localized app name used in [name].

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

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<void> 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';

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<void> 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';
 

packages/neon/neon_files/lib/utils/task.dart

@@ -13,7 +13,7 @@ sealed class FilesTask {
   @protected
   final streamController = StreamController<double>();
 
-  /// Task progress in percent [0, 1].
+  /// Task progress in percent `[0, 1]`.
   late final progress = streamController.stream.asBroadcastStream();
 }
 

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<void> 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';
 

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<void> 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';

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<void> 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';

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.