Merge pull request #1060 from keertip/nodocs

check for the <nodoc> tag in comments to generate docs for an element

Author: keertip

CHANGELOG.md

@@ -1,3 +1,6 @@
+## 0.8.5
+* [enhancement] do not document if there is a <nodoc> in the doc comment.
+
 ## 0.8.4
 * [enhancement] Only include generator metadata in the package `index.html` file.
 * [bug] Fixed the display of deprecated properties.

lib/dartdoc.dart

@@ -39,7 +39,7 @@ export 'src/package_meta.dart';
 
 const String name = 'dartdoc';
 // Update when pubspec version changes.
-const String version = '0.8.4';
+const String version = '0.8.4-dev';
 
 final String defaultOutDir = p.join('doc', 'api');
 

lib/src/model.dart

@@ -510,10 +510,13 @@ class Package implements Nameable, Documentable {
 
   Package(Iterable<LibraryElement> libraryElements, this.packageMeta) {
     libraryElements.forEach((element) {
-      var lib = new Library(element, this);
-      Library._libraryMap.putIfAbsent(lib.name, () => lib);
-      elementLibaryMap.putIfAbsent('${lib.kind}.${lib.name}', () => lib);
-      _libraries.add(lib);
+      // add only if the element should be included in the public api
+      if (isPublic(element)) {
+        var lib = new Library(element, this);
+        Library._libraryMap.putIfAbsent(lib.name, () => lib);
+        elementLibaryMap.putIfAbsent('${lib.kind}.${lib.name}', () => lib);
+        _libraries.add(lib);
+      }
     });
 
     _libraries.forEach((library) {
@@ -689,8 +692,8 @@ class Library extends ModelElement {
     _exportedNamespace.definedNames.values.forEach((element) {
       if (element is PropertyAccessorElement) elements.add(element.variable);
     });
-    elements..removeWhere(isPrivate);
     _variables = elements
+        .where(isPublic)
         .map((e) => new TopLevelVariable(e, this))
         .toList(growable: false)..sort(byName);
 
@@ -766,8 +769,7 @@ class Library extends ModelElement {
     elements.addAll(_exportedNamespace.definedNames.values
         .where((element) => element is FunctionElement));
 
-    elements..removeWhere(isPrivate);
-    _functions = elements.map((e) {
+    _functions = elements.where(isPublic).map((e) {
       return new ModelFunction(e, this);
     }).toList(growable: false)..sort(byName);
 
@@ -1133,7 +1135,7 @@ class Class extends ModelElement implements EnclosedElement {
     for (ExecutableElement value in vs) {
       if (value != null &&
           value is MethodElement &&
-          !value.isPrivate &&
+          isPublic(value) &&
           !value.isOperator &&
           value.enclosingElement != null) {
         if (!package.isDocumented(value.enclosingElement)) {
@@ -1261,7 +1263,7 @@ class Class extends ModelElement implements EnclosedElement {
     for (var value in vs) {
       if (value != null &&
           value is PropertyAccessorElement &&
-          !value.isPrivate &&
+          isPublic(value) &&
           value.enclosingElement != null) {
         // TODO: why is this here?
         var e = value.variable;

lib/src/model_utils.dart

@@ -11,7 +11,27 @@ import 'package:analyzer/src/generated/source_io.dart';
 
 bool isPrivate(Element e) => e.name.startsWith('_');
 
-bool isPublic(Element e) => !isPrivate(e);
+bool isPublic(Element e) {
+  if (isPrivate(e)) return false;
+  // check to see if element is part of the public api, that is it does not
+  // have a '#nodoc' in the documentation comment
+  if (e is PropertyAccessorElement && e.isSynthetic) {
+    var accessor = (e as PropertyAccessorElement);
+    if (accessor.correspondingSetter != null &&
+        !accessor.correspondingSetter.isSynthetic) {
+      e = accessor.correspondingSetter;
+    } else if (accessor.correspondingGetter != null &&
+        !accessor.correspondingGetter.isSynthetic) {
+      e = accessor.correspondingGetter;
+    } else {
+      e = accessor.variable;
+    }
+  }
+
+  var docComment = e.computeDocumentationComment();
+  if (docComment != null && docComment.contains('<nodoc>')) return false;
+  return true;
+}
 
 Iterable<LibraryElement> getSdkLibrariesToDocument(
     DartSdk sdk, AnalysisContext context) sync* {

pubspec.yaml

@@ -1,6 +1,6 @@
 name: dartdoc
 # Also update the `version` field in lib/dartdoc.dart.
-version: 0.8.4
+version: 0.8.4-dev
 author: Dart Team <[email protected]>
 description: A documentation generator for Dart.
 homepage: https://github.com/dart-lang/dartdoc

test_package/lib/example.dart

@@ -11,6 +11,9 @@ int function1(String s, bool b, lastParam) => 5;
 
 double number;
 
+/// top level var <nodoc>
+const DO_NOT_DOCUMENT = 'not documented';
+
 get y => 2;
 
 const String COLOR = 'red';
@@ -36,6 +39,13 @@ void set deprecatedSetter(int value) {}
 @deprecated
 int deprecatedField;
 
+/**
+ * class <nodoc>
+ */
+class unDocumented {
+  String s;
+}
+
 /// Sample class [String]
 class Apple {
   static const int n = 5;
@@ -45,6 +55,9 @@ class Apple {
   /// The read-write field `m`.
   int m = 0;
 
+  /// <nodoc> no docs
+  int notDocumented;
+
   ///Constructor
   Apple();
 
@@ -71,6 +84,11 @@ class Apple {
   ///     new Apple().m1();
   void m1() {}
 
+  /**
+   * <nodoc> method not documented
+   */
+  void notAPublicMethod() {}
+
   operator *(Apple other) => this;
 
   void printMsg(String msg, [bool linebreak]) {}

test_package/lib/excluded.dart

@@ -0,0 +1,12 @@
+/// This library is excluded from the documentation
+/// even though it is located in the lib folder by
+/// using the <nodoc> tag
+library excluded;
+
+export 'example.dart' show Apple;
+
+const EXCLUDE = 'exclude';
+
+class Excluded {
+  void excludedMethod(String s) {}
+}

test_package_docs/index.html

@@ -4,7 +4,7 @@
   <meta charset="utf-8">
   <meta http-equiv="X-UA-Compatible" content="IE=edge">
   <meta name="viewport" content="width=device-width, initial-scale=1">
-  <meta name="generator" content="made with love by dartdoc 0.8.4">
+  <meta name="generator" content="made with love by dartdoc 0.8.4-dev">
   <meta name="description" content="test_package API docs, for the Dart programming language.">
   <title>test_package - Dart API docs</title>