| OLD | NEW |
| 1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file |
| 2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
| 3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
| 4 | 4 |
| 5 /** | 5 /** |
| 6 * **docgen** is a tool for creating machine readable representations of Dart | 6 * **docgen** is a tool for creating machine readable representations of Dart |
| 7 * code metadata, including: classes, members, comments and annotations. | 7 * code metadata, including: classes, members, comments and annotations. |
| 8 * | 8 * |
| 9 * docgen is run on a `.dart` file or a directory containing `.dart` files. | 9 * docgen is run on a `.dart` file or a directory containing `.dart` files. |
| 10 * | 10 * |
| (...skipping 212 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 223 // Output libraries and classes to file after all information is generated. | 223 // Output libraries and classes to file after all information is generated. |
| 224 filteredEntities.where((e) => e is Class || e is Library).forEach((output) { | 224 filteredEntities.where((e) => e is Class || e is Library).forEach((output) { |
| 225 _writeIndexableToFile(output, outputToYaml); | 225 _writeIndexableToFile(output, outputToYaml); |
| 226 }); | 226 }); |
| 227 // Outputs a text file with a list of libraries available after creating all | 227 // Outputs a text file with a list of libraries available after creating all |
| 228 // the libraries. This will help the viewer know what libraries are available | 228 // the libraries. This will help the viewer know what libraries are available |
| 229 // to read in. | 229 // to read in. |
| 230 _writeToFile(filteredEntities.where((e) => e is Library) | 230 _writeToFile(filteredEntities.where((e) => e is Library) |
| 231 .map((e) => e.qualifiedName).join('\n'), 'library_list.txt', | 231 .map((e) => e.qualifiedName).join('\n'), 'library_list.txt', |
| 232 append: append); | 232 append: append); |
| 233 // Outputs all the qualified names documented. This will help generate search | 233 // Outputs all the qualified names documented with their type. |
| 234 // results. | 234 // This will help generate search results. |
| 235 _writeToFile(filteredEntities.map((e) => e.qualifiedName).join('\n'), | 235 _writeToFile(filteredEntities.map((e) => |
| 236 '${e.qualifiedName} ${e.typeName}').join('\n'), |
| 236 'index.txt', append: append); | 237 'index.txt', append: append); |
| 237 } | 238 } |
| 238 | 239 |
| 239 Library generateLibrary(dart2js.Dart2JsLibraryMirror library) { | 240 Library generateLibrary(dart2js.Dart2JsLibraryMirror library) { |
| 240 _currentLibrary = library; | 241 _currentLibrary = library; |
| 241 var result = new Library(library.qualifiedName, _commentToHtml(library), | 242 var result = new Library(library.qualifiedName, _commentToHtml(library), |
| 242 _variables(library.variables), | 243 _variables(library.variables), |
| 243 _methods(library.functions), | 244 _methods(library.functions), |
| 244 _classes(library.classes), _isHidden(library)); | 245 _classes(library.classes), _isHidden(library)); |
| 245 logger.fine('Generated library for ${result.name}'); | 246 logger.fine('Generated library for ${result.name}'); |
| (...skipping 265 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 511 | 512 |
| 512 /// Documentation comment with converted markdown. | 513 /// Documentation comment with converted markdown. |
| 513 String comment; | 514 String comment; |
| 514 | 515 |
| 515 /// Qualified Name of the owner of this Indexable Item. | 516 /// Qualified Name of the owner of this Indexable Item. |
| 516 /// For Library, owner will be ""; | 517 /// For Library, owner will be ""; |
| 517 String owner; | 518 String owner; |
| 518 | 519 |
| 519 Indexable(this.name, this.comment, this.qualifiedName, this.isPrivate, | 520 Indexable(this.name, this.comment, this.qualifiedName, this.isPrivate, |
| 520 this.owner); | 521 this.owner); |
| 522 |
| 523 /// The type of this member to be used in index.txt. |
| 524 String get typeName => ''; |
| 521 } | 525 } |
| 522 | 526 |
| 523 /** | 527 /** |
| 524 * A class containing contents of a Dart library. | 528 * A class containing contents of a Dart library. |
| 525 */ | 529 */ |
| 526 class Library extends Indexable { | 530 class Library extends Indexable { |
| 527 | 531 |
| 528 /// Top-level variables in the library. | 532 /// Top-level variables in the library. |
| 529 Map<String, Variable> variables; | 533 Map<String, Variable> variables; |
| 530 | 534 |
| 531 /// Top-level functions in the library. | 535 /// Top-level functions in the library. |
| 532 MethodGroup functions; | 536 MethodGroup functions; |
| 533 | 537 |
| 534 /// Classes defined within the library | 538 /// Classes defined within the library |
| 535 ClassGroup classes; | 539 ClassGroup classes; |
| 536 | 540 |
| 537 Library(String name, String comment, this.variables, | 541 Library(String name, String comment, this.variables, |
| 538 this.functions, this.classes, bool isPrivate) : super(name, comment, | 542 this.functions, this.classes, bool isPrivate) : super(name, comment, |
| 539 name, isPrivate, "") {} | 543 name, isPrivate, "") {} |
| 540 | 544 |
| 541 /// Generates a map describing the [Library] object. | 545 /// Generates a map describing the [Library] object. |
| 542 Map toMap() => { | 546 Map toMap() => { |
| 543 'name': name, | 547 'name': name, |
| 544 'qualifiedName': qualifiedName, | 548 'qualifiedName': qualifiedName, |
| 545 'comment': comment, | 549 'comment': comment, |
| 546 'variables': recurseMap(variables), | 550 'variables': recurseMap(variables), |
| 547 'functions': functions.toMap(), | 551 'functions': functions.toMap(), |
| 548 'classes': classes.toMap() | 552 'classes': classes.toMap() |
| 549 }; | 553 }; |
| 554 |
| 555 String get typeName => 'library'; |
| 550 } | 556 } |
| 551 | 557 |
| 552 /** | 558 /** |
| 553 * A class containing contents of a Dart class. | 559 * A class containing contents of a Dart class. |
| 554 */ | 560 */ |
| 555 class Class extends Indexable { | 561 class Class extends Indexable { |
| 556 | 562 |
| 557 /// List of the names of interfaces that this class implements. | 563 /// List of the names of interfaces that this class implements. |
| 558 List<Class> interfaces = []; | 564 List<Class> interfaces = []; |
| 559 | 565 |
| (...skipping 19 matching lines...) Expand all Loading... |
| 579 bool isAbstract; | 585 bool isAbstract; |
| 580 | 586 |
| 581 /// List of the meta annotations on the class. | 587 /// List of the meta annotations on the class. |
| 582 List<String> annotations; | 588 List<String> annotations; |
| 583 | 589 |
| 584 Class(String name, this.superclass, String comment, this.interfaces, | 590 Class(String name, this.superclass, String comment, this.interfaces, |
| 585 this.variables, this.methods, this.annotations, this.generics, | 591 this.variables, this.methods, this.annotations, this.generics, |
| 586 String qualifiedName, bool isPrivate, String owner, this.isAbstract) | 592 String qualifiedName, bool isPrivate, String owner, this.isAbstract) |
| 587 : super(name, comment, qualifiedName, isPrivate, owner); | 593 : super(name, comment, qualifiedName, isPrivate, owner); |
| 588 | 594 |
| 595 String get typeName => 'class'; |
| 596 |
| 589 /** | 597 /** |
| 590 * Returns a list of all the parent classes. | 598 * Returns a list of all the parent classes. |
| 591 */ | 599 */ |
| 592 List<Class> parent() { | 600 List<Class> parent() { |
| 593 var parent = superclass == null ? [] : [superclass]; | 601 var parent = superclass == null ? [] : [superclass]; |
| 594 parent.addAll(interfaces); | 602 parent.addAll(interfaces); |
| 595 return parent; | 603 return parent; |
| 596 } | 604 } |
| 597 | 605 |
| 598 /** | 606 /** |
| (...skipping 184 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 783 | 791 |
| 784 Map toMap() => { | 792 Map toMap() => { |
| 785 'name': name, | 793 'name': name, |
| 786 'qualifiedName': qualifiedName, | 794 'qualifiedName': qualifiedName, |
| 787 'comment': comment, | 795 'comment': comment, |
| 788 'return': returnType, | 796 'return': returnType, |
| 789 'parameters': recurseMap(parameters), | 797 'parameters': recurseMap(parameters), |
| 790 'annotations': annotations.map((a) => a.toMap()).toList(), | 798 'annotations': annotations.map((a) => a.toMap()).toList(), |
| 791 'generics': recurseMap(generics) | 799 'generics': recurseMap(generics) |
| 792 }; | 800 }; |
| 801 |
| 802 String get typeName => 'typedef'; |
| 793 } | 803 } |
| 794 | 804 |
| 795 /** | 805 /** |
| 796 * A class containing properties of a Dart variable. | 806 * A class containing properties of a Dart variable. |
| 797 */ | 807 */ |
| 798 class Variable extends Indexable { | 808 class Variable extends Indexable { |
| 799 | 809 |
| 800 bool isFinal; | 810 bool isFinal; |
| 801 bool isStatic; | 811 bool isStatic; |
| 802 bool isConst; | 812 bool isConst; |
| (...skipping 10 matching lines...) Expand all Loading... |
| 813 Map toMap() => { | 823 Map toMap() => { |
| 814 'name': name, | 824 'name': name, |
| 815 'qualifiedName': qualifiedName, | 825 'qualifiedName': qualifiedName, |
| 816 'comment': comment, | 826 'comment': comment, |
| 817 'final': isFinal.toString(), | 827 'final': isFinal.toString(), |
| 818 'static': isStatic.toString(), | 828 'static': isStatic.toString(), |
| 819 'constant': isConst.toString(), | 829 'constant': isConst.toString(), |
| 820 'type': new List.filled(1, type.toMap()), | 830 'type': new List.filled(1, type.toMap()), |
| 821 'annotations': annotations.map((a) => a.toMap()).toList() | 831 'annotations': annotations.map((a) => a.toMap()).toList() |
| 822 }; | 832 }; |
| 833 |
| 834 String get typeName => 'property'; |
| 823 } | 835 } |
| 824 | 836 |
| 825 /** | 837 /** |
| 826 * A class containing properties of a Dart method. | 838 * A class containing properties of a Dart method. |
| 827 */ | 839 */ |
| 828 class Method extends Indexable { | 840 class Method extends Indexable { |
| 829 | 841 |
| 830 /// Parameters for this method. | 842 /// Parameters for this method. |
| 831 Map<String, Parameter> parameters; | 843 Map<String, Parameter> parameters; |
| 832 | 844 |
| 833 bool isStatic; | 845 bool isStatic; |
| 834 bool isAbstract; | 846 bool isAbstract; |
| 835 bool isConst; | 847 bool isConst; |
| 848 bool isConstructor; |
| 849 bool isGetter; |
| 850 bool isSetter; |
| 851 bool isOperator; |
| 836 Type returnType; | 852 Type returnType; |
| 837 | 853 |
| 838 /// Qualified name to state where the comment is inherited from. | 854 /// Qualified name to state where the comment is inherited from. |
| 839 String commentInheritedFrom = ""; | 855 String commentInheritedFrom = ""; |
| 840 | 856 |
| 841 /// List of the meta annotations on the method. | 857 /// List of the meta annotations on the method. |
| 842 List<String> annotations; | 858 List<String> annotations; |
| 843 | 859 |
| 844 Method(String name, this.isStatic, this.isAbstract, this.isConst, | 860 Method(String name, this.isStatic, this.isAbstract, this.isConst, |
| 845 this.returnType, String comment, this.parameters, this.annotations, | 861 this.returnType, String comment, this.parameters, this.annotations, |
| 846 String qualifiedName, bool isPrivate, String owner) : super(name, comment, | 862 String qualifiedName, bool isPrivate, String owner, this.isConstructor, |
| 847 qualifiedName, isPrivate, owner); | 863 this.isGetter, this.isSetter, this.isOperator) |
| 864 : super(name, comment, qualifiedName, isPrivate, owner); |
| 848 | 865 |
| 849 /** | 866 /** |
| 850 * Makes sure that the method with an inherited equivalent have comments. | 867 * Makes sure that the method with an inherited equivalent have comments. |
| 851 */ | 868 */ |
| 852 void ensureCommentFor(Method inheritedMethod) { | 869 void ensureCommentFor(Method inheritedMethod) { |
| 853 if (comment.isNotEmpty) return; | 870 if (comment.isNotEmpty) return; |
| 854 entityMap[inheritedMethod.owner].ensureComments(); | 871 entityMap[inheritedMethod.owner].ensureComments(); |
| 855 comment = inheritedMethod.comment; | 872 comment = inheritedMethod.comment; |
| 856 commentInheritedFrom = inheritedMethod.commentInheritedFrom == '' ? | 873 commentInheritedFrom = inheritedMethod.commentInheritedFrom == '' ? |
| 857 inheritedMethod.qualifiedName : inheritedMethod.commentInheritedFrom; | 874 inheritedMethod.qualifiedName : inheritedMethod.commentInheritedFrom; |
| 858 } | 875 } |
| 859 | 876 |
| 860 /// Generates a map describing the [Method] object. | 877 /// Generates a map describing the [Method] object. |
| 861 Map toMap() => { | 878 Map toMap() => { |
| 862 'name': name, | 879 'name': name, |
| 863 'qualifiedName': qualifiedName, | 880 'qualifiedName': qualifiedName, |
| 864 'comment': comment, | 881 'comment': comment, |
| 865 'commentFrom': commentInheritedFrom, | 882 'commentFrom': commentInheritedFrom, |
| 866 'static': isStatic.toString(), | 883 'static': isStatic.toString(), |
| 867 'abstract': isAbstract.toString(), | 884 'abstract': isAbstract.toString(), |
| 868 'constant': isConst.toString(), | 885 'constant': isConst.toString(), |
| 869 'return': new List.filled(1, returnType.toMap()), | 886 'return': new List.filled(1, returnType.toMap()), |
| 870 'parameters': recurseMap(parameters), | 887 'parameters': recurseMap(parameters), |
| 871 'annotations': annotations.map((a) => a.toMap()).toList() | 888 'annotations': annotations.map((a) => a.toMap()).toList() |
| 872 }; | 889 }; |
| 890 |
| 891 String get typeName => isConstructor ? 'constructor' : |
| 892 isGetter ? 'getter' : isSetter ? 'setter' : |
| 893 isOperator ? 'operator' : 'method'; |
| 873 } | 894 } |
| 874 | 895 |
| 875 /** | 896 /** |
| 876 * A container to categorize methods into the following groups: setters, | 897 * A container to categorize methods into the following groups: setters, |
| 877 * getters, constructors, operators, regular methods. | 898 * getters, constructors, operators, regular methods. |
| 878 */ | 899 */ |
| 879 class MethodGroup { | 900 class MethodGroup { |
| 880 Map<String, Method> setters = {}; | 901 Map<String, Method> setters = {}; |
| 881 Map<String, Method> getters = {}; | 902 Map<String, Method> getters = {}; |
| 882 Map<String, Method> constructors = {}; | 903 Map<String, Method> constructors = {}; |
| 883 Map<String, Method> operators = {}; | 904 Map<String, Method> operators = {}; |
| 884 Map<String, Method> regularMethods = {}; | 905 Map<String, Method> regularMethods = {}; |
| 885 | 906 |
| 886 void addMethod(MethodMirror mirror) { | 907 void addMethod(MethodMirror mirror) { |
| 887 var method = new Method(mirror.simpleName, mirror.isStatic, | 908 var method = new Method(mirror.simpleName, mirror.isStatic, |
| 888 mirror.isAbstract, mirror.isConstConstructor, _type(mirror.returnType), | 909 mirror.isAbstract, mirror.isConstConstructor, _type(mirror.returnType), |
| 889 _commentToHtml(mirror), _parameters(mirror.parameters), | 910 _commentToHtml(mirror), _parameters(mirror.parameters), |
| 890 _annotations(mirror), mirror.qualifiedName, _isHidden(mirror), | 911 _annotations(mirror), mirror.qualifiedName, _isHidden(mirror), |
| 891 mirror.owner.qualifiedName); | 912 mirror.owner.qualifiedName, mirror.isConstructor, mirror.isGetter, |
| 913 mirror.isSetter, mirror.isOperator); |
| 892 entityMap[mirror.qualifiedName] = method; | 914 entityMap[mirror.qualifiedName] = method; |
| 893 _currentMember = mirror; | 915 _currentMember = mirror; |
| 894 if (mirror.isSetter) { | 916 if (mirror.isSetter) { |
| 895 setters[mirror.simpleName] = method; | 917 setters[mirror.simpleName] = method; |
| 896 } else if (mirror.isGetter) { | 918 } else if (mirror.isGetter) { |
| 897 getters[mirror.simpleName] = method; | 919 getters[mirror.simpleName] = method; |
| 898 } else if (mirror.isConstructor) { | 920 } else if (mirror.isConstructor) { |
| 899 constructors[mirror.simpleName] = method; | 921 constructors[mirror.simpleName] = method; |
| 900 } else if (mirror.isOperator) { | 922 } else if (mirror.isOperator) { |
| 901 operators[mirror.simpleName] = method; | 923 operators[mirror.simpleName] = method; |
| (...skipping 137 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1039 String qualifiedName; | 1061 String qualifiedName; |
| 1040 List<String> parameters; | 1062 List<String> parameters; |
| 1041 | 1063 |
| 1042 Annotation(this.qualifiedName, this.parameters); | 1064 Annotation(this.qualifiedName, this.parameters); |
| 1043 | 1065 |
| 1044 Map toMap() => { | 1066 Map toMap() => { |
| 1045 'name': qualifiedName, | 1067 'name': qualifiedName, |
| 1046 'parameters': parameters | 1068 'parameters': parameters |
| 1047 }; | 1069 }; |
| 1048 } | 1070 } |
| OLD | NEW |