proposal: `avoid_mixing_comment_identifiers`

`avoid_mixing_comment_identifiers`

Description

It is possible to accidentally mix dartdoc comments and normal comments. This is especially true when you have a long chunk of documentation. Ideally the lint will be able to identify such erroneous usage of //s in the middle of ///s.

/// Applies a theme to descendant widgets.
///
/// A theme configures the colors and typographic choices of Forui widgets. The actual configuration is stored in
/// a [FThemeData]. Descendant widgets obtain the current theme's [FThemeData] via either [ThemeBuildContext.theme],
/// or [FTheme.of]. When a widget uses either, it is automatically rebuilt if the theme later changes.
///
/// ```dart
/// class Parent extends StatelessWidget {
///   @override
///   Widget build(BuildContext context) => FTheme(
///      data: FThemes.zinc.light,
///      child: Child(),
///    );
///  }
/// 
//  class Child extends StatelessWidget { // <-- This line will not be included in the generated Dartdocs.
///    @override
///    Widget build(BuildContext context) {
///      final FThemeData theme = context.theme;
///      final FThemeData sameTheme = FTheme.of(context);
///      return const Placeholder();
///    }
///  }
/// ```

Details

Give a detailed description that should provide context and motivation. Ideally this could be used directly in the rule's documentation.

Kind

Guard against errors

Bad Examples

Add a few examples that demonstrate where this lint should fire.

Good Examples

Add a few examples that demonstrate a “good” adoption of this lint’s principle.

Discussion

Add any other motivation or useful context here.

dart-lang / linter