Source

void warnOnElement(Warnable warnable, PackageWarning kind,
    {String message, Locatable referredFrom}) {
  if (warnable != null) {
    // This sort of warning is only applicable to top level elements.
    if (kind == PackageWarning.ambiguousReexport) {
      Element topLevelElement = warnable.element;
      while (topLevelElement.enclosingElement is! CompilationUnitElement) {
        topLevelElement = topLevelElement.enclosingElement;
      }
      warnable = new ModelElement.from(
          topLevelElement, findOrCreateLibraryFor(topLevelElement));
    }
    if (warnable is Accessor) {
      // This might be part of a Field, if so, assign this warning to the field
      // rather than the Accessor.
      if ((warnable as Accessor).enclosingCombo != null)
        warnable = (warnable as Accessor).enclosingCombo;
    }
  } else {
    // If we don't have an element, we need a message to disambiguate.
    assert(message != null);
  }
  if (_packageWarningCounter.hasWarning(warnable?.element, kind, message)) {
    return;
  }
  // Elements that are part of the Dart SDK can have colons in their FQNs.
  // This confuses IntelliJ and makes it so it can't link to the location
  // of the error in the console window, so separate out the library from
  // the path.
  // TODO(jcollins-g): What about messages that may include colons?  Substituting
  //                   them out doesn't work as well there since it might confuse
  //                   the user, yet we still want IntelliJ to link properly.
  Tuple2<String, String> warnableStrings = nameAndLocation(warnable);
  String warnablePrefix = 'from';
  Tuple2<String, String> referredFromStrings = nameAndLocation(referredFrom);
  String referredFromPrefix = 'referred to by';
  String name = warnableStrings.item1;
  String warningMessage;
  switch (kind) {
    case PackageWarning.noCanonicalFound:
      // Fix these warnings by adding libraries with --include, or by using
      // --auto-include-dependencies.
      // TODO(jcollins-g): add a dartdoc flag to enable external website linking for non-canonical elements, using .packages for versioning
      // TODO(jcollins-g): support documenting multiple packages at once and linking between them
      warningMessage = "no canonical library found for ${name}, not linking";
      break;
    case PackageWarning.ambiguousReexport:
      // Fix these warnings by adding the original library exporting the
      // symbol with --include, or by using --auto-include-dependencies.
      // TODO(jcollins-g): add a dartdoc flag to force a particular resolution order for (or drop) ambiguous reexports
      warningMessage =
          "ambiguous reexport of ${name}, canonicalization candidates: ${message}";
      break;
    case PackageWarning.noLibraryLevelDocs:
      warningMessage =
          "${warnable.fullyQualifiedName} has no library level documentation comments";
      break;
    case PackageWarning.ambiguousDocReference:
      warningMessage = "ambiguous doc reference ${message}";
      break;
    case PackageWarning.categoryOrderGivesMissingPackageName:
      warningMessage =
          "--category-order gives invalid package name: '${message}'";
      break;
    case PackageWarning.unresolvedDocReference:
      warningMessage = "unresolved doc reference [${message}]";
      if (referredFrom == null) {
        referredFrom = warnable.documentationFrom;
      }
      referredFromPrefix = 'in documentation inherited from';
      break;
    case PackageWarning.brokenLink:
      warningMessage = 'dartdoc generated a broken link to: ${message}';
      warnablePrefix = 'to element';
      referredFromPrefix = 'linked to from';
      break;
    case PackageWarning.orphanedFile:
      warningMessage = 'dartdoc generated a file orphan: ${message}';
      break;
    case PackageWarning.unknownFile:
      warningMessage =
          'dartdoc detected an unknown file in the doc tree: ${message}';
      break;
    case PackageWarning.missingFromSearchIndex:
      warningMessage =
          'dartdoc generated a file not in the search index: ${message}';
      break;
    case PackageWarning.typeAsHtml:
      // The message for this warning can contain many punctuation and other symbols,
      // so bracket with a triple quote for defense.
      warningMessage = 'generic type handled as HTML: """${message}"""';
      break;
  }

  List<String> messageParts = [warningMessage];
  if (warnable != null)
    messageParts.add(
        "${warnablePrefix} ${warnableStrings.item1}: ${warnableStrings.item2}");
  if (referredFrom != null && referredFrom != warnable) {
    messageParts.add(
        "${referredFromPrefix} ${referredFromStrings.item1}: ${referredFromStrings.item2}");
  }
  String fullMessage;
  if (messageParts.length <= 2) {
    fullMessage = messageParts.join(', ');
  } else {
    fullMessage = messageParts.join('\n    ');
  }

  packageWarningCounter.addWarning(
      warnable?.element, kind, message, fullMessage);
}