Tidy some comments (#3741)

Tidy some comments:

* Move the `Locatable.documentationFrom` comment from an override to the
  highest declaration.
* Make a few comments more idiomatic.

Author: srawlins

lib/src/model/documentation_comment.dart

@@ -38,13 +38,6 @@ mixin DocumentationComment
 
   List<DocumentationComment>? _documentationFrom;
 
-  /// The [ModelElement](s) from which we will get documentation.
-  ///
-  /// Can be more than one if this is a [Field] composing documentation from
-  /// multiple [Accessor]s.
-  ///
-  /// This will walk up the inheritance hierarchy to find docs, if the current
-  /// class doesn't have docs for this element.
   @override
   List<DocumentationComment> get documentationFrom =>
       _documentationFrom ??= () {
@@ -72,11 +65,19 @@ mixin DocumentationComment
   /// like `///`, `//`, `/*`, `*/`.
   String get documentationComment => element.documentationComment ?? '';
 
-  /// True if [this] has a synthetic/inherited or local documentation
-  /// comment.  False otherwise.
+  /// Whether `this` has a synthetic/inherited or local documentation comment,
+  /// and false otherwise.
   bool get hasDocumentationComment => element.documentationComment != null;
 
-  /// Returns true if the raw documentation comment has a 'nodoc' indication.
+  /// Whether the raw documentation comment is considered to be 'nodoc', an
+  /// attribute indicating that any documentation should not be included in
+  /// dartdoc's generated output.
+  ///
+  /// An element is considered to be 'nodoc' if any of the following are true:
+  /// * a global 'nodoc' configuration has been set for this element (this
+  ///   feature is deprecated),
+  /// * the element has no documentation comment,
+  /// * the documentation comment contains the `@nodoc` dartdoc directive.
   late final bool hasNodoc = () {
     if (packageGraph.configSetsNodocFor(element.source!.fullName)) {
       return true;

lib/src/model/inheritable.dart

@@ -125,7 +125,12 @@ mixin Inheritable on ContainerMember {
 
   Inheritable? get overriddenElement;
 
-  /// True if this [Inheritable] is overriding a superclass.
+  /// Whether this [Inheritable] is overriding a member from a superclass.
+  ///
+  /// This is distinct from [isInherited]. An inheritable member which is an
+  /// override is explicitly written in its container. An inheritable member
+  /// which is implicitly included in a container is "inherited", and not an
+  /// override.
   late final bool isOverride = () {
     // The canonical version of the enclosing element -- not
     // [canonicalEnclosingElement], as that is the element enclosing the

lib/src/model/locatable.dart

@@ -3,9 +3,17 @@
 // BSD-style license that can be found in the LICENSE file.
 
 import 'package:analyzer/dart/element/element.dart' show Element;
+import 'package:dartdoc/src/model/model.dart';
 
 /// Something that can be located for warning purposes.
 mixin Locatable {
+  /// The [Locatable](s) from which we will get documentation.
+  ///
+  /// Can be more than one if this is a [Field] composing documentation from
+  /// multiple [Accessor]s.
+  ///
+  /// This will walk up the inheritance hierarchy to find docs, if the current
+  /// class doesn't have docs for this element.
   List<Locatable> get documentationFrom;
 
   /// True if documentationFrom contains only one item, [this].

lib/src/model/package_graph.dart

@@ -903,8 +903,12 @@ class PackageGraph with CommentReferable, Nameable {
   /// Glob lookups can be expensive.  Cache per filename.
   final _configSetsNodocFor = HashMap<String, bool>();
 
-  /// Given an element's location, look up the nodoc configuration data and
-  /// determine whether to unconditionally treat the element as "nodoc".
+  /// Given an element's [fullName], look up the nodoc configuration data and
+  /// determine whether to unconditionally treat the element as "nodoc", an
+  /// attribute indicating that documentation should not be included in
+  /// dartdoc's generated output.
+  ///
+  /// This configuration setting is deprecated.
   bool configSetsNodocFor(String fullName) {
     return _configSetsNodocFor.putIfAbsent(fullName, () {
       var file = resourceProvider.getFile(fullName);