Skip to content

Commit f13623e

Browse files
authored
[jnigen] API docs (#3715)
1 parent be61879 commit f13623e

7 files changed

Lines changed: 56 additions & 14 deletions

File tree

‎pkgs/jnigen/lib/src/config/config_exception.dart‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
/// Exception thrown when a configuration value is invalid.
66
class ConfigException implements Exception {
77
ConfigException(this.message);
8+
9+
/// Error message describing the configuration failure.
810
String message;
911

1012
@override

‎pkgs/jnigen/lib/src/config/config_types.dart‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,10 @@ final _currentVersion = Version(1, 0, 0);
3131
/// JAR files will be automatically added to the source path and class path
3232
/// respectively.
3333
class MavenDownloads {
34+
/// Default directory for unpacking Maven sources (`mvn_java/`).
3435
static final defaultMavenSourceDir = Uri.directory('mvn_java');
36+
37+
/// Default directory for downloading Maven JAR files (`mvn_jar/`).
3538
static final defaultMavenJarDir = Uri.directory('mvn_jar');
3639

3740
MavenDownloads({
@@ -194,6 +197,8 @@ enum SummarizerBackend {
194197
doclet,
195198
}
196199

200+
/// Parses [name] into a [SummarizerBackend] enum value, or returns
201+
/// [defaultVal].
197202
SummarizerBackend? getSummarizerBackend(
198203
String? name,
199204
SummarizerBackend? defaultVal,
@@ -221,6 +226,7 @@ enum OutputStructure {
221226
singleFile,
222227
}
223228

229+
/// Parses [name] into an [OutputStructure] enum value, or returns [defaultVal].
224230
OutputStructure getOutputStructure(String? name, OutputStructure defaultVal) {
225231
return _getEnumValueFromString(
226232
OutputStructure.values.valuesMap(),

‎pkgs/jnigen/lib/src/generate_bindings.dart‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ import 'logging/logging.dart';
2222
import 'summary/summary.dart';
2323
import 'tools/tools.dart';
2424

25+
/// Collects UTF-8 output from [stream] and writes it to [buffer].
2526
void collectOutputStream(Stream<List<int>> stream, StringBuffer buffer) =>
2627
stream.transform(const Utf8Decoder()).forEach(buffer.write);
2728

‎pkgs/jnigen/lib/src/tools/android_sdk_tools.dart‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,20 +12,28 @@ import '../logging/logging.dart';
1212

1313
class _AndroidToolsException implements Exception {
1414
_AndroidToolsException(this.message);
15+
16+
/// Error message describing the failure.
1517
String message;
18+
1619
@override
1720
String toString() => message;
1821
}
1922

23+
/// Exception thrown when the Android SDK cannot be found.
2024
class SdkNotFoundException extends _AndroidToolsException {
2125
SdkNotFoundException(super.message);
2226
}
2327

28+
/// Exception thrown when a Gradle operation fails.
2429
class GradleException extends _AndroidToolsException {
2530
GradleException(super.message);
2631
}
2732

33+
/// Utilities for locating Android SDK components and running Gradle stubs.
2834
class AndroidSdkTools {
35+
/// Locates and returns the Android SDK root directory from the
36+
/// `ANDROID_SDK_ROOT` environment variable.
2937
static Uri getAndroidSdkRoot() {
3038
final envVar = Platform.environment['ANDROID_SDK_ROOT'];
3139
if (envVar == null) {
@@ -68,6 +76,7 @@ class AndroidSdkTools {
6876
'control system or manually remove the stub functions named '
6977
'$_gradleGetClasspathTaskName and / or $_gradleGetSourcesTaskName.';
7078

79+
/// Finds the path to `android.jar` in [sdkRoot] according to [versionOrder].
7180
static Future<Uri?> getAndroidJarPath(
7281
{required Uri sdkRoot, required List<int> versionOrder}) async =>
7382
await _getFile(sdkRoot, 'platforms', versionOrder, 'android.jar');

‎pkgs/jnigen/lib/src/tools/build_summarizer.dart‎

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -18,20 +18,18 @@ import '../logging/logging.dart';
1818
import '../util/find_package.dart';
1919
import 'gradle_tools.dart';
2020

21-
final toolPath = join('.', '.dart_tool', 'jnigen');
22-
final mvnTargetDir = join(toolPath, 'target');
23-
final gradleBuildDir = join('.', 'java', 'build');
24-
final gradleTargetDir = join(gradleBuildDir, 'libs');
25-
final jarFile = join(gradleTargetDir, 'ApiSummarizer.jar');
26-
final targetJarFile = join(toolPath, 'ApiSummarizer.jar');
21+
final _toolPath = join('.', '.dart_tool', 'jnigen');
22+
final _jarFile = join('.', 'java', 'build', 'libs', 'ApiSummarizer.jar');
23+
final _targetJarFile = join(_toolPath, 'ApiSummarizer.jar');
2724

25+
/// Builds the ApiSummarizer JAR using Gradle.
2826
Future<void> buildApiSummarizer() async {
2927
final pkg = await findPackageRoot('jnigen');
3028
if (pkg == null) {
3129
log.fatal('package jnigen not found!');
3230
}
3331
final gradleWrapper = await GradleTools.getGradleWExecutable();
34-
await Directory(toolPath).create(recursive: true);
32+
await Directory(_toolPath).create(recursive: true);
3533
final gradleArgs = [
3634
'-p',
3735
pkg.resolve('java/').toFilePath(),
@@ -43,7 +41,7 @@ Future<void> buildApiSummarizer() async {
4341
try {
4442
final gradleProc = await Process.run(
4543
gradleWrapper!.toFilePath(), gradleArgs,
46-
workingDirectory: toolPath,
44+
workingDirectory: _toolPath,
4745
runInShell: true,
4846
environment: jni_util.javaEnvironment);
4947
final exitCode = gradleProc.exitCode;
@@ -53,7 +51,7 @@ Future<void> buildApiSummarizer() async {
5351

5452
if (exitCode == 0) {
5553
sourceJar.copySync(
56-
File(targetJarFile).uri.toFilePath(windows: Platform.isWindows));
54+
File(_targetJarFile).uri.toFilePath(windows: Platform.isWindows));
5755
} else {
5856
printError(gradleProc.stdout);
5957
printError(gradleProc.stderr);
@@ -62,16 +60,17 @@ Future<void> buildApiSummarizer() async {
6260
} finally {}
6361
}
6462

63+
/// Builds the ApiSummarizer JAR if it has not been built or is stale.
6564
Future<void> buildSummarizerIfNotExists({bool force = false}) async {
6665
// TODO(#43): This function cannot be invoked concurrently because 2 processes
6766
// will start building summarizer at once. Introduce a locking mechnanism so
6867
// that when one process is building summarizer JAR, other process waits using
6968
// exponential backoff.
70-
final jarExists = await File(jarFile).exists();
71-
final targetJarExists = await File(targetJarFile).exists();
69+
final jarExists = await File(_jarFile).exists();
70+
final targetJarExists = await File(_targetJarFile).exists();
7271
final isJarStale = jarExists &&
7372
await isPackageModifiedAfter(
74-
'jnigen', await File(jarFile).lastModified(), 'java/');
73+
'jnigen', await File(_jarFile).lastModified(), 'java/');
7574
if (isJarStale) {
7675
log.info('Rebuilding ApiSummarizer component since sources '
7776
'have changed. This might take some time.');

‎pkgs/jnigen/lib/src/tools/gradle_tools.dart‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,13 @@ import 'package:path/path.dart';
1111
import '../logging/logging.dart';
1212
import '../util/find_package.dart';
1313

14+
/// Tooling utilities for resolving and downloading Gradle and Maven
15+
/// dependencies.
1416
class GradleTools {
17+
/// Current working directory.
1518
static final currentDir = Directory('.');
1619

17-
// Maven Central root location
20+
/// Maven Central root location.
1821
static String repoLocation = 'https://repo1.maven.org/maven2';
1922

2023
/// Helper method since we can't pass inheritStdio option to [Process.run].
@@ -29,6 +32,7 @@ class GradleTools {
2932
return proc.exitCode;
3033
}
3134

35+
/// Returns the URI to the Gradle wrapper executable for the current platform.
3236
static Future<Uri?> getGradleWExecutable() async {
3337
final pkg = await findPackageRoot('jnigen');
3438
if (Platform.isLinux || Platform.isMacOS) {
@@ -80,6 +84,7 @@ class GradleTools {
8084
await _runGradleCommand(deps, targetDir, taskName: 'extractSourceJars');
8185
}
8286

87+
/// Creates a minimal stub Java project in [rootTempDir] for Gradle builds.
8388
static Future<void> createStubProject(Directory rootTempDir) async {
8489
final sourceDir = await Directory(join(rootTempDir.path, 'src/main/java/'))
8590
.create(recursive: true);
@@ -168,6 +173,8 @@ class MavenDependency {
168173
MavenDependency(this.groupID, this.artifactID, this.version,
169174
{this.otherTags = const {}});
170175

176+
/// Parses a Maven dependency coordinate in `groupID:artifactID:version`
177+
/// format.
171178
factory MavenDependency.fromString(String fullName) {
172179
final components = fullName.split(':');
173180
if (components.length != 3) {
@@ -176,24 +183,38 @@ class MavenDependency {
176183
return MavenDependency(components[0], components[1], components[2]);
177184
}
178185

179-
String groupID, artifactID, version;
186+
/// Maven group ID.
187+
String groupID;
188+
189+
/// Maven artifact ID.
190+
String artifactID;
191+
192+
/// Maven version.
193+
String version;
194+
195+
/// Additional metadata tags for this dependency.
180196
Map<String, String> otherTags;
181197

198+
/// URL for browsing Javadoc documentation on javadoc.io.
182199
String get javadocUrl =>
183200
'https://javadoc.io/doc/$groupID/$artifactID/$version';
184201

202+
/// URL for direct static Javadoc documentation on javadoc.io.
185203
String get staticJavadocUrl =>
186204
'https://javadoc.io/static/$groupID/$artifactID/$version';
187205

206+
/// Generates a Gradle dependency declaration string for [configuration].
188207
String toGradleDependency(String configuration) {
189208
return '$configuration("$groupID:$artifactID:$version")';
190209
}
191210

211+
/// Returns the JAR filename for this dependency.
192212
String filename({bool isSource = true}) {
193213
final extension = isSource ? '-sources.jar' : '.jar';
194214
return '$artifactID-$version$extension';
195215
}
196216

217+
/// Resolves the full URL to the dependency artifact under [repoLocation].
197218
String toURLString(String repoLocation) {
198219
final parts = <String>[repoLocation];
199220
parts.addAll(groupID.split('.'));

‎pkgs/jnigen/lib/tools.dart‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,8 @@
22
// for details. All rights reserved. Use of this source code is governed by a
33
// BSD-style license that can be found in the LICENSE file.
44

5+
/// Tooling utilities for Android SDK resolution, Gradle dependencies, and
6+
/// summarizer building.
7+
library;
8+
59
export 'src/tools/tools.dart';

0 commit comments

Comments
 (0)