dartdoc: Stop section-divider comments from getting absorbed into docs

Before this change, if you hover in your IDE over an identifier whose
declaration happens to be the first one after one of these section
dividers, the doc shown would begin with a long string of slashes.
After all, the divider line did start with "///".

The choice of "|" as the substitute was fairly arbitrary.  I tried a
space first, and felt it interrupted the divider too much and made it
look like just another line of comments.

Done with a bit of Perl and Git:

  $ perl -i -0pe 's,^\s*//\K(?=//),|,gm' $(git grep -l //// '*.dart')

Author: gnprice

lib/example/sticky_header.dart

@@ -198,14 +198,14 @@ class ExampleVerticalDouble extends StatelessWidget {
   }
 }
 
-////////////////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////////////////
 //
 // That's it!
 //
 // The rest of this file is boring infrastructure for navigating to the
 // different examples, and for having some content to put inside them.
 //
-////////////////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////////////////
 
 class WideHeader extends StatelessWidget {
   const WideHeader({super.key, required this.i});

lib/model/content.dart

@@ -1016,7 +1016,7 @@ class GlobalTimeNode extends InlineContentNode {
   }
 }
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 
 /// Parser for the inline-content subtrees within Zulip content HTML.
 ///

lib/model/store.dart

@@ -369,7 +369,7 @@ abstract class PerAccountStoreBase {
   @protected
   final CorePerAccountStore core;
 
-  ////////////////////////////////
+  //|//////////////////////////////
   // Where data comes from in the first place.
 
   GlobalStore get _globalStore => core._globalStore;
@@ -378,7 +378,7 @@ abstract class PerAccountStoreBase {
 
   String get queueId => core.queueId;
 
-  ////////////////////////////////
+  //|//////////////////////////////
   // Data attached to the realm or the server.
 
   /// Always equal to `account.realmUrl` and `connection.realmUrl`.
@@ -395,7 +395,7 @@ abstract class PerAccountStoreBase {
 
   String get zulipVersion => account.zulipVersion;
 
-  ////////////////////////////////
+  //|//////////////////////////////
   // Data attached to the self-account on the realm.
 
   int get accountId => core.accountId;
@@ -536,10 +536,10 @@ class PerAccountStore extends PerAccountStoreBase with
        _channels = channels,
        _messages = messages;
 
-  ////////////////////////////////////////////////////////////////
+  //|//////////////////////////////////////////////////////////////
   // Data.
 
-  ////////////////////////////////
+  //|//////////////////////////////
   // Where data comes from in the first place.
 
   UpdateMachine? get updateMachine => _updateMachine;
@@ -559,7 +559,7 @@ class PerAccountStore extends PerAccountStoreBase with
     notifyListeners();
   }
 
-  ////////////////////////////////
+  //|//////////////////////////////
   // Data attached to the realm or the server.
 
   // (User groups come before even realm settings,
@@ -574,7 +574,7 @@ class PerAccountStore extends PerAccountStoreBase with
   RealmStore get realmStore => _realm;
   final RealmStoreImpl _realm;
 
-  ////////////////////////////////
+  //|//////////////////////////////
   // The realm's repertoire of available emoji.
 
   @override
@@ -604,7 +604,7 @@ class PerAccountStore extends PerAccountStoreBase with
 
   EmojiStoreImpl _emoji;
 
-  ////////////////////////////////
+  //|//////////////////////////////
   // Data attached to the self-account on the realm.
 
   final UserSettings userSettings;
@@ -615,7 +615,7 @@ class PerAccountStore extends PerAccountStoreBase with
 
   final TypingNotifier typingNotifier;
 
-  ////////////////////////////////
+  //|//////////////////////////////
   // Users and data about them.
 
   @override
@@ -693,7 +693,7 @@ class PerAccountStore extends PerAccountStoreBase with
     }
   }
 
-  ////////////////////////////////
+  //|//////////////////////////////
   // Streams, topics, and stuff about them.
 
   @override
@@ -735,7 +735,7 @@ class PerAccountStore extends PerAccountStoreBase with
     }
   }
 
-  ////////////////////////////////
+  //|//////////////////////////////
   // Messages, and summaries of messages.
 
   @override
@@ -797,13 +797,13 @@ class PerAccountStore extends PerAccountStoreBase with
 
   final RecentSenders recentSenders;
 
-  ////////////////////////////////
+  //|//////////////////////////////
   // Other digests of data.
 
   final AutocompleteViewManager autocompleteViewManager = AutocompleteViewManager();
 
   // End of data.
-  ////////////////////////////////////////////////////////////////
+  //|//////////////////////////////////////////////////////////////
 
   /// Called when the app is reassembled during debugging, e.g. for hot reload.
   ///

test/example_data.dart

@@ -25,7 +25,7 @@ void _checkPositive(int? value, String description) {
   assert(value == null || value > 0, '$description should be positive');
 }
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // Error objects.
 //
 
@@ -71,7 +71,7 @@ ZulipApiException apiExceptionUnauthorized({String routeName = 'someRoute'}) {
     data: {}, message: 'Invalid API key');
 }
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // Time values.
 //
 
@@ -85,7 +85,7 @@ int utcTimestamp([DateTime? dateTime]) {
   return dateTime.toUtc().millisecondsSinceEpoch ~/ 1000;
 }
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // Realm-wide (or server-wide) metadata.
 //
 
@@ -231,7 +231,7 @@ RealmEmojiItem realmEmojiItem({
   );
 }
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // Users and accounts.
 //
 
@@ -386,7 +386,7 @@ final Account otherAccount = account(
   apiKey: '6dxT4b73BYpCTU+i4BB9LAKC5h/CufqY', // A Zulip API key is 32 digits of base64.
 );
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // Data attached to the self-account on the realm
 //
 
@@ -408,7 +408,7 @@ SavedSnippet savedSnippet({
   );
 }
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // Streams and subscriptions.
 //
 
@@ -523,7 +523,7 @@ UserTopicItem userTopicItem(
   );
 }
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // Messages, and pieces of messages.
 //
 
@@ -867,7 +867,7 @@ Submessage submessage({
   );
 }
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // Aggregate data structures.
 //
 
@@ -902,7 +902,7 @@ UnreadMessagesSnapshot unreadMsgs({
 }
 const _unreadMsgs = unreadMsgs;
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // Events.
 //
 
@@ -1175,7 +1175,7 @@ ChannelUpdateEvent channelUpdateEvent(
   );
 }
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // The entire per-account or global state.
 //
 

test/flutter_checks.dart

@@ -7,7 +7,7 @@ import 'package:flutter/material.dart';
 import 'package:flutter/rendering.dart';
 import 'package:flutter/services.dart';
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // From the Flutter engine, i.e. from dart:ui.
 //
 
@@ -40,15 +40,15 @@ extension FontVariationChecks on Subject<FontVariation> {
   Subject<double> get value => has((x) => x.value, 'value');
 }
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // From 'package:flutter/foundation.dart'.
 //
 
 extension ValueListenableChecks<T> on Subject<ValueListenable<T>> {
   Subject<T> get value => has((c) => c.value, 'value');
 }
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // From 'package:flutter/services.dart'.
 //
 
@@ -62,7 +62,7 @@ extension TextEditingValueChecks on Subject<TextEditingValue> {
   Subject<TextRange> get composing => has((x) => x.composing, 'composing');
 }
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // From 'package:flutter/animation.dart'.
 //
 
@@ -71,7 +71,7 @@ extension AnimationChecks<T> on Subject<Animation<T>> {
   Subject<T> get value => has((d) => d.value, 'value');
 }
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // From 'package:flutter/painting.dart'.
 //
 
@@ -97,7 +97,7 @@ extension InlineSpanChecks on Subject<InlineSpan> {
   Subject<TextStyle?> get style => has((x) => x.style, 'style');
 }
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // From 'package:flutter/rendering.dart'.
 //
 
@@ -110,7 +110,7 @@ extension RenderParagraphChecks on Subject<RenderParagraph> {
   Subject<bool> get didExceedMaxLines => has((x) => x.didExceedMaxLines, 'didExceedMaxLines');
 }
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // From 'package:flutter/widgets.dart'.
 //
 
@@ -192,7 +192,7 @@ extension PageRouteChecks<T> on Subject<PageRoute<T>> {
   Subject<bool> get fullscreenDialog => has((x) => x.fullscreenDialog, 'fullscreenDialog');
 }
 
-////////////////////////////////////////////////////////////////
+//|//////////////////////////////////////////////////////////////
 // From 'package:flutter/material.dart'.
 //
 

test/model/binding.dart

@@ -422,7 +422,7 @@ class TestZulipBinding extends ZulipBinding {
 }
 
 class FakeFirebaseMessaging extends Fake implements FirebaseMessaging {
-  ////////////////////////////////
+  //|//////////////////////////////
   // Permissions.
 
   NotificationSettings requestPermissionResult = const NotificationSettings(
@@ -471,7 +471,7 @@ class FakeFirebaseMessaging extends Fake implements FirebaseMessaging {
     return requestPermissionResult;
   }
 
-  ////////////////////////////////
+  //|//////////////////////////////
   // Tokens.
 
   String? _initialToken;
@@ -527,7 +527,7 @@ class FakeFirebaseMessaging extends Fake implements FirebaseMessaging {
     }
   }
 
-  ////////////////////////////////
+  //|//////////////////////////////
   // Messages.
 
   StreamController<RemoteMessage> onMessage = StreamController.broadcast();