Skip to content

Refactor handling of generateDocs:false #4095

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 26, 2025
Merged

Refactor handling of generateDocs:false #4095

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
30ec961
Refactor handling of generateDocs:false
sigurdm Aug 26, 2025
9f0ea7a
Remove redundant Generator abstraction
sigurdm Aug 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 1 addition & 4 deletions bin/dartdoc.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,5 @@ void main(List<String> arguments) {
final packageConfigProvider = PhysicalPackageConfigProvider();
final packageBuilder =
PubPackageBuilder(config, pubPackageMetaProvider, packageConfigProvider);
final dartdoc = config.generateDocs
? Dartdoc.fromContext(config, packageBuilder)
: Dartdoc.withEmptyGenerator(config, packageBuilder);
dartdoc.executeGuarded();
Dartdoc.fromContext(config, packageBuilder).executeGuarded();
}
56 changes: 31 additions & 25 deletions lib/src/dartdoc.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@ import 'dart:io' show Platform, exitCode, stderr;
import 'package:analyzer/file_system/file_system.dart';
import 'package:dartdoc/src/dartdoc_options.dart';
import 'package:dartdoc/src/failure.dart';
import 'package:dartdoc/src/generator/empty_generator.dart';
import 'package:dartdoc/src/generator/generator.dart';
import 'package:dartdoc/src/generator/html_generator.dart';
import 'package:dartdoc/src/logging.dart';
Expand All @@ -27,10 +26,28 @@ const String programName = 'dartdoc';
// Update when pubspec version changes by running `pub run build_runner build`
const String dartdocVersion = packageVersion;

/// Used for the generateDocs:false option.
///
/// Writes nothing.
class NoFileWriter implements FileWriter {
@override
void write(String filePath, String content, {Warnable? element}) {
// Do nothing
}

@override
void writeBytes(String filePath, List<int> content,
{bool allowOverwrite = false}) {
// Do nothing
}

@override
Set<String> get writtenFiles => {};
}

class DartdocFileWriter implements FileWriter {
final String _outputDir;
@override
final ResourceProvider resourceProvider;
final ResourceProvider _resourceProvider;
final Map<String, Warnable?> _fileElementMap = {};
@override
final Set<String> writtenFiles = {};
Expand All @@ -43,7 +60,7 @@ class DartdocFileWriter implements FileWriter {

DartdocFileWriter(
this._outputDir,
this.resourceProvider, {
this._resourceProvider, {
int maxFileCount = 0,
int maxTotalSize = 0,
}) : _maxFileCount = maxFileCount,
Expand Down Expand Up @@ -115,8 +132,8 @@ class DartdocFileWriter implements FileWriter {
/// Returns the file at [outFile] relative to [_outputDir], creating the
/// parent directory if necessary.
File _getFile(String outFile) {
var file = resourceProvider
.getFile(resourceProvider.pathContext.join(_outputDir, outFile));
var file = _resourceProvider
.getFile(_resourceProvider.pathContext.join(_outputDir, outFile));
var parent = file.parent;
if (!parent.exists) {
parent.create();
Expand Down Expand Up @@ -144,19 +161,6 @@ class Dartdoc {
@visibleForTesting
set generator(Generator newGenerator) => _generator = newGenerator;

/// Factory method that builds Dartdoc with an empty generator.
factory Dartdoc.withEmptyGenerator(
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI, the dart tool is using this in its implementation of dart doc; see https://github.com/dart-lang/sdk/blob/main/pkg/dartdev/lib/src/commands/doc.dart#L119.

I'm sure its possible to update the tool for this change, but we'll want to do that as part of the next roll of this repo into the sdk.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! I was unaware of that. I'll make a migration CL...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gotcha; tracking the work here so we don't lose track: #4100

DartdocOptionContext config,
PackageBuilder packageBuilder,
) {
return Dartdoc._(
config,
config.resourceProvider.getFolder('UNUSED'),
initEmptyGenerator(),
packageBuilder,
);
}

/// Builds Dartdoc with a generator determined by [context].
factory Dartdoc.fromContext(
DartdocGeneratorOptionContext context,
Expand All @@ -165,12 +169,14 @@ class Dartdoc {
var resourceProvider = context.resourceProvider;
var outputPath = resourceProvider.pathContext.absolute(context.output);
var outputDir = resourceProvider.getFolder(outputPath)..create();
var writer = DartdocFileWriter(
outputPath,
resourceProvider,
maxFileCount: context.maxFileCount,
maxTotalSize: context.maxTotalSize,
);
var writer = context.generateDocs
? DartdocFileWriter(
outputPath,
resourceProvider,
maxFileCount: context.maxFileCount,
maxTotalSize: context.maxTotalSize,
)
: NoFileWriter();
return Dartdoc._(
context,
outputDir,
Expand Down
6 changes: 3 additions & 3 deletions lib/src/dartdoc_options.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1278,6 +1278,9 @@ class DartdocGeneratorOptionContext extends DartdocOptionContext {
bool get useBaseHref => optionSet['useBaseHref'].valueAt(context);

String? get resourcesDir => optionSet['resourcesDir'].valueAt(context);

/// Whether to generate docs or perform a dry run.
bool get generateDocs => optionSet['generateDocs'].valueAt(context);
}

class DartdocProgramOptionContext extends DartdocGeneratorOptionContext
Expand All @@ -1288,9 +1291,6 @@ class DartdocProgramOptionContext extends DartdocGeneratorOptionContext
DartdocProgramOptionContext.fromDefaultContextLocation(
super.optionSet, super.resourceProvider)
: super.fromDefaultContextLocation();

/// Whether to generate docs or perform a dry run.
bool get generateDocs => optionSet['generateDocs'].valueAt(context);
}

List<DartdocOption<bool>> createDartdocProgramOptions(
Expand Down
40 changes: 0 additions & 40 deletions lib/src/generator/empty_generator.dart
View file
Open in desktop

This file was deleted.

Loading
Loading