Using Domain-Specific Languages (DSLs) to Document API — the Kotlin DSL story

Slide 1

Slide 1 text

@_Unsolved_ June 06, 2023 Using Domain-Specific Languages (DSLs) to Document API — the Kotlin DSL story Lana Novikova, Writerside, JetBrains

Slide 2

Slide 2 text

How it all started

Slide 3

Slide 3 text

Internal hackathon

Slide 4

Slide 4 text

What is a DSL? DSL programming language higher level of abstraction specific class of problems particular domain

Slide 5

Slide 5 text

External vs Internal DSLs External DSL Internal DSL Is a separate language Uses host language grammar, syntax and parser Has custom features Uses host language features

Slide 6

Slide 6 text

How it works

Slide 7

Slide 7 text

Simplistic documentation DSL val content = StardustDslContentProvider { p { +"Hello DSL"} list { li { +"List item 1" } li { +"List item 2" } } this } A paragraph A list

Slide 8

Slide 8 text

Simplistic documentation DSL

Slide 9

Slide 9 text

Simplistic documentation DSL val content = StardustDslContentProvider { table { tr { td { + "Parameter name" } td { + "Parameter type" } } tr { td { + "Value 1" } td { + "Value 2" } } this } A table

Slide 10

Slide 10 text

Simplistic documentation DSL

Slide 11

Slide 11 text

Simplistic documentation DSL xml(""" Step 1 Step 2 Step 3 """.trimIndent() ) Other language injection

Slide 12

Slide 12 text

Simplistic documentation DSL

Slide 13

Slide 13 text

Simplistic documentation DSL runConfigurations.forEach { runConfiguration -> chapter(id = runConfiguration.name, title = runConfiguration.name) { p { +runConfiguration.description} xml("""""") table(headerStyle = Table.HeaderStyle.NONE) { runConfiguration.properties.forEach { property -> tr { td { code { +property.key } } td { +property.value } } } } } } Combine the two

Slide 14

Slide 14 text

Simplistic documentation DSL

Slide 15

Slide 15 text

Did you just change the angle brackets to curly brackets?

Slide 16

Slide 16 text

It’s actually curly brackets and + No

Slide 17

Slide 17 text

But what is so cool about it? Docs-as-code on a new level Separate data and presentation Update the representation once without changing data Combine declarative and imperative approach to docs Extensibility Use ANY abilities that come up to mind

Slide 18

Slide 18 text

Separate data and its presentation

Slide 19

Slide 19 text

Separation of content and presentation Separation of content and presentation Separation of data and presentation Lightweight languages Kotlin DSL

Slide 20

Slide 20 text

No content

Slide 21

Slide 21 text

Docs-as-code on a new level

Slide 22

Slide 22 text

Docs-as-code

Slide 23

Slide 23 text

Docs-are-code

Slide 24

Slide 24 text

Wait! Are you suggesting that the writer writes code now?

Slide 25

Slide 25 text

No, but it is good to have a choice Write docs using markup Extend it using code constructions

Slide 26

Slide 26 text

Use practices brought to us by developers ● Refactorings ● Completions ● Dead code detection ● Parameters/variables ● Extracting into ● Changing visibility

Slide 27

Slide 27 text

Time for demonstration

Slide 28

Slide 28 text

No content

Slide 29

Slide 29 text

No content

Slide 30

Slide 30 text

No content

Slide 31

Slide 31 text

No content

Slide 32

Slide 32 text

No content

Slide 33

Slide 33 text

No content

Slide 34

Slide 34 text

No content

Slide 35

Slide 35 text

No content

Slide 36

Slide 36 text

No content

Slide 37

Slide 37 text

No content

Slide 38

Slide 38 text

No content

Slide 39

Slide 39 text

No content

Slide 40

Slide 40 text

No content

Slide 41

Slide 41 text

No content

Slide 42

Slide 42 text

546 API methods in total

Slide 43

Slide 43 text

The idea of generating HTML from code is not new

Slide 44

Slide 44 text

Why Kotlin?

Slide 45

Slide 45 text

0. We are from JetBrains

Slide 46

Slide 46 text

1. It is pragmatic and has a short learning curve

Slide 47

Slide 47 text

2. Seamless integration with the JVM ecosystem

Slide 48

Slide 48 text

Extensibility

Slide 49

Slide 49 text

A few examples where (else) you can go:

Slide 50

Slide 50 text

A few examples where (else) you can go: ● Parse and integrate any format out there, including XML, JSON, YAML, custom serialization formats, and even take objects from application runtime

Slide 51

Slide 51 text

Slide 52

Slide 52 text

Slide 53

Slide 53 text

A few examples where (else) you can go: ● Parse and integrate any format out there, including XML, JSON, YAML, custom serialization formats, and even take objects from application runtime ● Add mappings and enrich with additional content ● Cycles and conditional statements ● Use any JVM libraries, for example, natural language processing or readability analysis lib

Slide 54

Slide 54 text

Slide 55

Slide 55 text

Pitfalls

Slide 56

Slide 56 text

1. You need to know what’s possible

Slide 57

Slide 57 text

2. Flexibility leads to fragmentation

Slide 58

Slide 58 text

And one more thing

Slide 59

Slide 59 text

It helps you to start coding more smoothly I will help you learn Lambda functions variables conditionals nullable Extension functions

Slide 60

Slide 60 text

Thanks! Have a nice Kotlin DSL!

Slide 61

Slide 61 text

me { name = "Lana Novikova" twitter = "_Unsolved_" linkedin = "svetlana-novikova" } Come to the writerside

Slide 62

Slide 62 text

jetbrains.com Let’s stay in touch — @_Unsolved_ Come to the writerside @svetlnovikova https://www.linkedin.com/in/svetlana-novikova/