add a --no-generate-docs flag that is faster and only displays warnings #1909

jcollins-g · 2019-01-22T23:18:22Z

Allows the user to use dartdoc to show dartdoc errors and warnings only without actually generating documentation.

Also has some changes to output in the common case.

Without --no-generate-docs:

~/dart/dartdoc
$ dart bin/dartdoc.dart
Documenting dartdoc...
parsing /usr/local/google/home/jcollins/dart/dartdoc/lib/dartdoc.dart...
parsing /usr/local/google/home/jcollins/dart/all_sdks/2.1.1-dev.1.0/lib/async/async.dart...
parsing /usr/local/google/home/jcollins/dart/all_sdks/2.1.1-dev.1.0/lib/collection/collection.dart...

[...]
parsing /usr/local/google/home/jcollins/.pub-cache/hosted/pub.dartlang.org/matcher-0.12.3+1/lib/mirror_matchers.dart...
Initialized dartdoc with 668 libraries in 47.0 seconds
documenting dartdoc
Generating docs for library dartdoc from package:dartdoc/dartdoc.dart...
  warning: unresolved doc reference [Property], from dartdoc.TopLevelContainer: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart:5464:16)
  warning: unresolved doc reference [_MarkdownCommentReference._getResultsForClass]
    from dartdoc.Accessor.namePart: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart)
    in documentation inherited from dartdoc.models.Nameable.namePart: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart:4548:14)
  warning: unresolved doc reference [_MarkdownCommentReference._getResultsForClass]
    from dartdoc.Class.allModelElementsByNamePart: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart)
    in documentation inherited from dartdoc.Class.allModelElementsByNamePart: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart:681:39)
  warning: unresolved doc reference [_MarkdownCommentReference._getResultsForClass]
    from dartdoc.Nameable.namePart: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart)
    in documentation inherited from dartdoc.Nameable.namePart: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart:4548:14)
  warning: unresolved doc reference [config.autoIncludeDependencies]
    from dartdoc.Package.isLocal: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart)
    in documentation inherited from dartdoc.Package.isLocal: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart:5889:12)
  warning: unresolved doc reference [toolPath]
    from dartdoc.Snapshot.needsSnapshot: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/dartdoc_options.dart)
    in documentation inherited from dartdoc.Snapshot.needsSnapshot: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/dartdoc_options.dart:209:12)
Validating docs...
found 6 warnings and 0 errors
Documented 1 public library in 7.6 seconds
Success! Docs generated into /usr/local/google/home/jcollins/dart/dartdoc/doc/api

With --no-generate-docs:

~/dart/dartdoc
$ dart bin/dartdoc.dart --no-generate-docs
Documenting dartdoc...
  warning: unresolved doc reference [_MarkdownCommentReference._getResultsForClass]
    from dartdoc.Accessor.namePart: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart)
    in documentation inherited from dartdoc.models.Nameable.namePart: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart:4548:14)
  warning: unresolved doc reference [_MarkdownCommentReference._getResultsForClass]
    from dartdoc.Nameable.namePart: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart)
    in documentation inherited from dartdoc.Nameable.namePart: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart:4548:14)
  warning: unresolved doc reference [_MarkdownCommentReference._getResultsForClass]
    from dartdoc.Class.allModelElementsByNamePart: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart)
    in documentation inherited from dartdoc.Class.allModelElementsByNamePart: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart:681:39)
  warning: unresolved doc reference [config.autoIncludeDependencies]
    from dartdoc.Package.isLocal: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart)
    in documentation inherited from dartdoc.Package.isLocal: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart:5889:12)
  warning: unresolved doc reference [toolPath]
    from dartdoc.Snapshot.needsSnapshot: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/dartdoc_options.dart)
    in documentation inherited from dartdoc.Snapshot.needsSnapshot: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/dartdoc_options.dart:209:12)
  warning: unresolved doc reference [Property], from dartdoc.TopLevelContainer: (file:///usr/local/google/home/jcollins/dart/dartdoc/lib/src/model.dart:5464:16)
found 6 warnings and 0 errors

coveralls · 2019-01-23T00:34:03Z

Coverage increased (+0.1%) to 93.909% when pulling 5398d6a on allow-non-writing into 737755a on master.

pq · 2019-01-23T00:41:33Z

lib/src/logging.dart

+            writingProgress = true;
+            stdout.write(message);
+          } else {
+            print(message);


should this use stdout too?

This code is making use of the side-effect of print that adds a \n.

kevmoo · 2019-01-23T00:52:03Z

@jcollins-g – any particular thing you want me to look at?

jcollins-g · 2019-01-23T00:54:36Z

@kevmoo I mostly put you on the list as you said you had an implementation of this in #1537 and so might be interested.

jcollins-g added 5 commits January 14, 2019 16:26

basic non-documenting mode works

7f8a0db

Basically works now, needs tests

2e39d93

Merge branch 'master' into allow-non-writing

0c6541e

Add a test

900dc3e

dartfmt

341761e

googlebot added the cla: yes Google CLA check succeeded. label Jan 22, 2019

jcollins-g added 3 commits January 22, 2019 15:32

Cleanup

8e41406

Add test for doc generation presence/absence with --quiet

1f939fa

Fix packages output parsing problem

5398d6a

jcollins-g changed the title ~~WIP: add a --no-generate-docs flag that is faster and only displays warnings~~ add a --no-generate-docs flag that is faster and only displays warnings Jan 23, 2019

jcollins-g requested review from pq and kevmoo January 23, 2019 00:39

pq approved these changes Jan 23, 2019

View reviewed changes

jcollins-g merged commit 6ec18b5 into master Jan 23, 2019

jcollins-g deleted the allow-non-writing branch January 23, 2019 14:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add a --no-generate-docs flag that is faster and only displays warnings #1909

add a --no-generate-docs flag that is faster and only displays warnings #1909

jcollins-g commented Jan 22, 2019 •

edited

Loading

coveralls commented Jan 23, 2019

pq Jan 23, 2019

jcollins-g Jan 23, 2019

kevmoo commented Jan 23, 2019

jcollins-g commented Jan 23, 2019

add a --no-generate-docs flag that is faster and only displays warnings #1909

add a --no-generate-docs flag that is faster and only displays warnings #1909

Conversation

jcollins-g commented Jan 22, 2019 • edited Loading

coveralls commented Jan 23, 2019

pq Jan 23, 2019

Choose a reason for hiding this comment

jcollins-g Jan 23, 2019

Choose a reason for hiding this comment

kevmoo commented Jan 23, 2019

jcollins-g commented Jan 23, 2019

jcollins-g commented Jan 22, 2019 •

edited

Loading