check for the <nodoc> tag in comments to generate docs for an element
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d497adf..b502e1b 100644
--- a/CHANGELOG.md
+++ b/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.
diff --git a/lib/dartdoc.dart b/lib/dartdoc.dart
index b69bc40..1d9e5b3 100644
--- a/lib/dartdoc.dart
+++ b/lib/dartdoc.dart
@@ -39,7 +39,7 @@
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');
diff --git a/lib/src/model.dart b/lib/src/model.dart
index 284d069..cc1762c 100644
--- a/lib/src/model.dart
+++ b/lib/src/model.dart
@@ -510,10 +510,13 @@
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 @@
_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 @@
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 @@
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 @@
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;
diff --git a/lib/src/model_utils.dart b/lib/src/model_utils.dart
index 83a5a0c..b1124f0 100644
--- a/lib/src/model_utils.dart
+++ b/lib/src/model_utils.dart
@@ -11,7 +11,27 @@
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* {
diff --git a/pubspec.yaml b/pubspec.yaml
index e9c2077..379d9e2 100644
--- a/pubspec.yaml
+++ b/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 <misc@dartlang.org>
description: A documentation generator for Dart.
homepage: https://github.com/dart-lang/dartdoc
diff --git a/test_package/lib/example.dart b/test_package/lib/example.dart
index 1032c75..f9f629f 100644
--- a/test_package/lib/example.dart
+++ b/test_package/lib/example.dart
@@ -11,6 +11,9 @@
double number;
+/// top level var <nodoc>
+const DO_NOT_DOCUMENT = 'not documented';
+
get y => 2;
const String COLOR = 'red';
@@ -36,6 +39,13 @@
@deprecated
int deprecatedField;
+/**
+ * class <nodoc>
+ */
+class unDocumented {
+ String s;
+}
+
/// Sample class [String]
class Apple {
static const int n = 5;
@@ -45,6 +55,9 @@
/// The read-write field `m`.
int m = 0;
+ /// <nodoc> no docs
+ int notDocumented;
+
///Constructor
Apple();
@@ -71,6 +84,11 @@
/// new Apple().m1();
void m1() {}
+ /**
+ * <nodoc> method not documented
+ */
+ void notAPublicMethod() {}
+
operator *(Apple other) => this;
void printMsg(String msg, [bool linebreak]) {}
diff --git a/test_package/lib/excluded.dart b/test_package/lib/excluded.dart
new file mode 100644
index 0000000..c2cd9a9
--- /dev/null
+++ b/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) {}
+}
diff --git a/test_package_docs/index.html b/test_package_docs/index.html
index 29a8e69..8c64967 100644
--- a/test_package_docs/index.html
+++ b/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>
