Skip to content

Commit e15541f

Browse files
sargunvsargunv
authored
write docs for java and js (#156)
1 parent 288c883 commit e15541f

File tree

6 files changed

+439
-83
lines changed

6 files changed

+439
-83
lines changed

‎docs/docs/index.md

Lines changed: 64 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -3,96 +3,95 @@
33
## Introduction
44

55
PokeKotlin is a modern [Kotlin Multiplatform] client for [PokéAPI]. You can use
6-
it to integrate all sorts of Pokémon data into your Kotlin projects.
6+
it to integrate all sorts of Pokémon data into your Kotlin, Java, JS, or Swift
7+
projects.
78

8-
Under the hood, it's built on [Ktor], [Kotlin Serialization], and coroutines.
9+
Under the hood, it's built on [Ktor], [Kotlin Serialization], and [coroutines].
910

10-
## Supported platforms
11+
## Features
1112

12-
- Kotlin/JVM, including Android
13-
- Kotlin/JS for browser and Node
14-
- Kotlin/WASM for browser and Node
15-
- Kotlin/Native for Linux, Windows, macOS, iOS, tvOS, and watchOS
13+
- **Multiplatform**: Works on JVM, Node, the web, and native platforms like iOS,
14+
macOS, Linux, and Windows.
15+
- **Caching**: Uses Ktor's built-in caching to reduce API calls and speed up
16+
responses.
17+
- **Asynchronous**: Built on coroutines for non-blocking calls.
1618

17-
## Installation
19+
## Languages
1820

19-
This library is published via [Maven Central], and snapshot builds of `main` are
20-
additionally available on [GitHub Packages].
21+
### Kotlin
2122

22-
=== "Releases (Maven Central)"
23+
On Kotlin, we support all major Kotlin Multiplatform targets, including JVM, JS,
24+
and native platforms like iOS and macOS. The API is based on `suspend fun`
25+
calls:
2326

24-
The latest release is **v{{ gradle.release_version }}**. In your Gradle version catalog, add:
25-
26-
```toml title="libs.versions.toml"
27-
[libraries]
28-
pokekotlin = { module = "co.pokeapi.pokekotlin:pokekotlin", version = "{{ gradle.release_version }}" }
29-
```
30-
31-
=== "Snapshots (GitHub Packages)"
32-
33-
!!! warning
34-
35-
The published documentation is for the latest release, and may not match the snapshot
36-
version. If using snapshots, always refer to the [latest source code][repo] for the most
37-
accurate information.
38-
39-
First, follow [GitHub's guide][gh-packages-guide] for authenticating to GitHub Packages. Your
40-
settings.gradle.kts should have something like this:
41-
42-
```kotlin title="settings.gradle.kts"
43-
repositories {
44-
maven {
45-
url = uri("https://maven.pkg.github.com/pokeapi/pokekotlin")
46-
credentials {
47-
username = project.findProperty("gpr.user") as String? ?: System.getenv("GH_USERNAME")
48-
password = project.findProperty("gpr.key") as String? ?: System.getenv("GH_TOKEN")
49-
}
50-
}
27+
```kotlin
28+
fun main() = runBlocking {
29+
with(PokeApi) {
30+
val list = getPokemonSpeciesList(offset = 0, limit = 10)
31+
for (handle in list.results) {
32+
val species = handle.get()
33+
println("Found: $species")
5134
}
52-
```
35+
}
36+
}
37+
```
5338

54-
The latest snapshot is **v{{ gradle.snapshot_version }}**. In your Gradle version catalog, add:
39+
On JVM targets, the Java APIs below are also available. Similarly, on JS
40+
targets, the JavaScript APIs below are available.
5541

56-
```toml title="libs.versions.toml"
57-
[libraries]
58-
pokekotlin = { module = "co.pokeapi.pokekotlin:pokekotlin", version = "{{ gradle.snapshot_version }}" }
59-
```
42+
### Java
6043

61-
In your Gradle build script, add:
44+
For Java, we provide an API based on `CompletableFuture`:
6245

63-
```kotlin title="build.gradle.kts"
64-
commonMain.dependencies {
65-
implementation(libs.maplibre.compose)
46+
```java
47+
public class Example {
48+
public static void main(String[] args) {
49+
PokeApi.getPokemonSpeciesListAsync(0, 10).thenAccept(list -> {
50+
for (NamedHandle<PokemonSpecies> handle : list.getResults()) {
51+
PokeApi.getAsync(handle).thenAccept(species -> {
52+
System.out.println("Found: " + species);
53+
});
54+
}
55+
});
56+
}
6657
}
6758
```
6859

69-
## Usage
70-
71-
For basic usage, use the global `PokeApi` instance:
60+
We also provide a synchronous API:
7261

73-
```kotlin
74-
-8<- "src/commonTest/kotlin/co/pokeapi/pokekotlin/example/example.kt:simple"
62+
```java
63+
public class Example {
64+
public static void main(String[] args) {
65+
PokemonSpeciesList list = PokeApi.getPokemonSpeciesListBlocking(0, 10);
66+
for (NamedHandle<PokemonSpecies> handle : list.getResults()) {
67+
PokemonSpecies species = PokeApi.getBlocking(handle);
68+
System.out.println("Found: " + species);
69+
}
70+
}
71+
}
7572
```
7673

77-
By default, the client will connect to the official `https://pokeapi.co/`
78-
instance and cache results in memory.
74+
### JS
7975

80-
If you want to customize the client, create a custom instance of the client:
76+
For JavaScript, we provide an ESM module with TypeScript typings and a
77+
`Promise`-based API that works in browsers and in Node:
8178

82-
```kotlin
83-
-8<- "src/commonTest/kotlin/co/pokeapi/pokekotlin/example/example.kt:custom"
79+
```typescript
80+
import { PokeApi } from "@pokeapi/pokekotlin";
81+
82+
const list = await PokeApi.Default.getPokemonSpeciesListAsync(0, 10);
83+
for (const handle of list.results) {
84+
const species = await PokeApi.Default.getAsync(handle);
85+
console.log(`Found: ${species}`);
86+
}
8487
```
8588

86-
For further details, see the Dokka [API Reference](./api).
89+
### Swift
90+
91+
The Swift package is not yet published.
8792

8893
[Kotlin Multiplatform]: https://kotlinlang.org/docs/multiplatform.html
8994
[PokéAPI]: https://pokeapi.co/
90-
[Maven Central]: https://central.sonatype.com/namespace/co.pokeapi.pokekotlin
91-
[GitHub Packages]:
92-
https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry
93-
[gh-packages-guide]:
94-
https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry#using-a-published-package
95-
[repo]: https://github.com/pokeapi/pokekotlin
9695
[Ktor]: https://ktor.io/
9796
[Kotlin Serialization]: https://github.com/Kotlin/kotlinx.serialization
9897
[coroutines]: https://kotlinlang.org/docs/coroutines-guide.html

‎docs/docs/usage-java.md

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# Usage with Java
2+
3+
## Overview
4+
5+
PokeKotlin is a Kotlin Multiplatform library that compiles to JVM bytecode,
6+
making it compatible with Java projects. The library provides both asynchronous
7+
(`CompletableFuture`-based) and blocking APIs for Java interoperability.
8+
9+
## Installation
10+
11+
### Gradle
12+
13+
This library is published via [Maven Central], and snapshot builds of `main` are
14+
additionally available on [GitHub Packages][gh-packages-gradle].
15+
16+
=== "Releases (Maven Central)"
17+
18+
The latest release is **v{{ gradle.release_version }}**. In your Gradle build script, add:
19+
20+
```groovy title="build.gradle"
21+
dependencies {
22+
implementation 'co.pokeapi.pokekotlin:pokekotlin-jvm:{{ gradle.release_version }}'
23+
}
24+
```
25+
26+
Or if using Kotlin DSL:
27+
28+
```kotlin title="build.gradle.kts"
29+
dependencies {
30+
implementation("co.pokeapi.pokekotlin:pokekotlin-jvm:{{ gradle.release_version }}")
31+
}
32+
```
33+
34+
=== "Snapshots (GitHub Packages)"
35+
36+
!!! warning
37+
38+
The published documentation is for the latest release, and may not match the snapshot
39+
version. If using snapshots, always refer to the [latest source code][repo] for the most
40+
accurate information.
41+
42+
First, follow [GitHub's guide][gh-packages-guide-gradle] for authenticating to GitHub Packages. Your
43+
build.gradle should have something like this:
44+
45+
```groovy title="build.gradle"
46+
repositories {
47+
maven {
48+
url = "https://maven.pkg.github.com/pokeapi/pokekotlin"
49+
credentials {
50+
username = project.findProperty("gpr.user") ?: System.getenv("GH_USERNAME")
51+
password = project.findProperty("gpr.key") ?: System.getenv("GH_TOKEN")
52+
}
53+
}
54+
}
55+
```
56+
57+
The latest snapshot is **v{{ gradle.snapshot_version }}**. Add the dependency:
58+
59+
```groovy title="build.gradle"
60+
dependencies {
61+
implementation 'co.pokeapi.pokekotlin:pokekotlin-jvm:{{ gradle.snapshot_version }}'
62+
}
63+
```
64+
65+
### Maven
66+
67+
=== "Releases (Maven Central)"
68+
69+
The latest release is **v{{ gradle.release_version }}**. In your pom.xml, add:
70+
71+
```xml title="pom.xml"
72+
<dependency>
73+
<groupId>co.pokeapi.pokekotlin</groupId>
74+
<artifactId>pokekotlin-jvm</artifactId>
75+
<version>{{ gradle.release_version }}</version>
76+
</dependency>
77+
```
78+
79+
=== "Snapshots (GitHub Packages)"
80+
81+
!!! warning
82+
83+
The published documentation is for the latest release, and may not match the snapshot
84+
version. If using snapshots, always refer to the [latest source code][repo] for the most
85+
accurate information.
86+
87+
First, configure [GitHub Packages][gh-packages-guide-maven] authentication in your settings.xml
88+
or pom.xml:
89+
90+
```xml title="pom.xml"
91+
<repositories>
92+
<repository>
93+
<id>github</id>
94+
<url>https://maven.pkg.github.com/pokeapi/pokekotlin</url>
95+
</repository>
96+
</repositories>
97+
```
98+
99+
The latest snapshot is **v{{ gradle.snapshot_version }}**. Add the dependency:
100+
101+
```xml title="pom.xml"
102+
<dependency>
103+
<groupId>co.pokeapi.pokekotlin</groupId>
104+
<artifactId>pokekotlin-jvm</artifactId>
105+
<version>{{ gradle.snapshot_version }}</version>
106+
</dependency>
107+
```
108+
109+
## Usage
110+
111+
For basic usage, use the global `PokeApi.Default` instance.
112+
113+
### Asynchronous API (Recommended)
114+
115+
For asynchronous usage with CompletableFuture:
116+
117+
```java
118+
public class AsyncExample {
119+
public static void main(String[] args) {
120+
// Get a list of Pokémon species
121+
PokeApi.Default.getPokemonSpeciesListAsync(0, 10).thenAccept(list -> {
122+
for (NamedHandle<PokemonSpecies> handle : list.getResults()) {
123+
// Get each species by its handle
124+
PokeApi.Default.getAsync(handle).thenAccept(species ->
125+
System.out.println("Found: " + species)
126+
).exceptionally(e -> {
127+
System.err.println("Error fetching species: " + e.getMessage());
128+
e.printStackTrace();
129+
return null;
130+
});
131+
}
132+
}).exceptionally(e -> {
133+
System.err.println("Error fetching species list: " + e.getMessage());
134+
e.printStackTrace();
135+
return null;
136+
});
137+
}
138+
}
139+
```
140+
141+
### Blocking API
142+
143+
For synchronous/blocking usage:
144+
145+
```java
146+
public class BlockingExample {
147+
public static void main(String[] args) {
148+
try {
149+
// Get a list of Pokémon species
150+
PaginatedList<PokemonSpecies> list = PokeApi.Default.getPokemonSpeciesListBlocking(0, 10);
151+
152+
for (Handle<PokemonSpecies> handle : list.getResults()) {
153+
// Get each species by its handle
154+
PokemonSpecies species = PokeApi.Default.getBlocking(handle);
155+
System.out.println("Found: " + species);
156+
}
157+
} catch (Exception e) {
158+
System.err.println("Error: " + e.getMessage());
159+
e.printStackTrace();
160+
}
161+
}
162+
}
163+
```
164+
165+
### Further details
166+
167+
Every PokeApi endpoint has a corresponding asynchronous and blocking method in
168+
the `PokeApi` instance. By default, the client will connect to the official
169+
`https://pokeapi.co/` instance and cache results in memory. To customize the
170+
client, you can create your own instance of `PokeApi.Custom`.
171+
172+
For further details, see the Kotlin [API Reference](./api). Any function like
173+
`suspend fun getExample()` available in the Kotlin API has corresponding Java
174+
APIs like `CompletableFuture<Example> getExampleAsync()` for asynchronous
175+
access, or `Example getExampleBlocking()` for synchronous access.
176+
177+
[Maven Central]: https://central.sonatype.com/namespace/co.pokeapi.pokekotlin
178+
[gh-packages-gradle]:
179+
https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry
180+
[gh-packages-guide-gradle]:
181+
https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry#using-a-published-package
182+
[gh-packages-guide-maven]:
183+
https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry#installing-a-package
184+
[repo]: https://github.com/pokeapi/pokekotlin

0 commit comments

Comments
 (0)