pkg/docgen/lib/src/models/method.dart

// Copyright (c) 2014, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

library docgen.models.method;

import 'package:markdown/markdown.dart' as markdown;

import '../exports/mirrors_util.dart' as dart2js_util;
import '../exports/source_mirrors.dart';

import '../library_helpers.dart';

import 'class.dart';
import 'doc_gen_type.dart';
import 'dummy_mirror.dart';
import 'indexable.dart';
import 'model_helpers.dart';
import 'owned_indexable.dart';
import 'parameter.dart';


/// A class containing properties of a Dart method.
class Method extends OwnedIndexable<MethodMirror> {

  /// Parameters for this method.
  final Map<String, Parameter> parameters;

  final bool isStatic;
  final bool isAbstract;
  final bool isConst;
  final DocGenType returnType;
  Method methodInheritedFrom;

  /// Qualified name to state where the comment is inherited from.
  String commentInheritedFrom = "";

  factory Method(MethodMirror mirror, Indexable owner,
      [Method methodInheritedFrom]) {
    var method = getDocgenObject(mirror, owner);
    if (method is DummyMirror) {
      method = new Method._(mirror, owner, methodInheritedFrom);
    }
    return method;
  }

  Method._(MethodMirror mirror, Indexable owner, this.methodInheritedFrom)
      : returnType = new DocGenType(mirror.returnType, owner.owningLibrary),
        isStatic = mirror.isStatic,
        isAbstract = mirror.isAbstract,
        isConst = mirror.isConstConstructor,
        parameters = createParameters(mirror.parameters, owner),
        super(mirror, owner);

  Method get originallyInheritedFrom => methodInheritedFrom == null ?
      this : methodInheritedFrom.originallyInheritedFrom;

  /// Look for the specified name starting with the current member, and
  /// progressively working outward to the current library scope.
  String findElementInScope(String name) {
    var lookupFunc = determineLookupFunc(name);

    var memberScope = lookupFunc(this.mirror, name);
    if (memberScope != null) {
      // do we check for a dummy mirror returned here and look up with an owner
      // higher ooooor in getDocgenObject do we include more things in our
      // lookup
      var result = getDocgenObject(memberScope, owner);
      if (result is DummyMirror && owner.owner != null
          && owner.owner is! DummyMirror) {
        var aresult = getDocgenObject(memberScope, owner.owner);
        if (aresult is! DummyMirror) result = aresult;
      }
      if (result is DummyMirror) return packagePrefix + result.docName;
      return result.packagePrefix + result.docName;
    }

    if (owner != null) {
      var result = owner.findElementInScope(name);
      if (result != null) return result;
    }
    return super.findElementInScope(name);
  }

  String get docName {
    if (mirror.isConstructor) {
      // We name constructors specially -- including the class name again and a
      // "-" to separate the constructor from its name (if any).
      return '${owner.docName}.${dart2js_util.nameOf(mirror.owner)}-'
          '${dart2js_util.nameOf(mirror)}';
    }
    return super.docName;
  }

  String get qualifiedName => packagePrefix + docName;

  /// Makes sure that the method with an inherited equivalent have comments.
  void ensureCommentFor(Method inheritedMethod) {
    if (comment.isNotEmpty) return;

    comment = inheritedMethod.commentToHtml(this);
    unresolvedComment = inheritedMethod.unresolvedComment;
    commentInheritedFrom = inheritedMethod.commentInheritedFrom == '' ?
        new DummyMirror(inheritedMethod.mirror).docName :
        inheritedMethod.commentInheritedFrom;
  }

  /// Generates a map describing the [Method] object.
  Map toMap() => {
    'name': name,
    'qualifiedName': qualifiedName,
    'comment': comment,
    'commentFrom': (methodInheritedFrom != null &&
        commentInheritedFrom == methodInheritedFrom.docName ? ''
        : commentInheritedFrom),
    'inheritedFrom': (methodInheritedFrom == null? '' :
        originallyInheritedFrom.docName),
    'static': isStatic,
    'abstract': isAbstract,
    'constant': isConst,
    'return': [returnType.toMap()],
    'parameters': recurseMap(parameters),
    'annotations': annotations.map((a) => a.toMap()).toList()
  };

  String get typeName {
    if (mirror.isConstructor) return 'constructor';
    if (mirror.isGetter) return 'getter';
    if (mirror.isSetter) return 'setter';
    if (mirror.isOperator) return 'operator';
    return 'method';
  }

  String get comment {
    if (commentField != null) return commentField;
    if (owner is Class) {
      (owner as Class).ensureComments();
    }
    var result = super.comment;
    if (result == '' && methodInheritedFrom != null) {
      // This should be NOT from the MIRROR, but from the COMMENT.
      methodInheritedFrom.comment; // Ensure comment field has been populated.
      unresolvedComment = methodInheritedFrom.unresolvedComment;

      comment = unresolvedComment == null ? '' :
        markdown.markdownToHtml(unresolvedComment.trim(),
            linkResolver: fixReference, inlineSyntaxes: MARKDOWN_SYNTAXES);
      commentInheritedFrom = comment != '' ?
          methodInheritedFrom.commentInheritedFrom : '';
      result = comment;
    }
    return result;
  }

  bool isValidMirror(DeclarationMirror mirror) => mirror is MethodMirror;
}