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

Transcript

1. @_Unsolved_ June 06, 2023 Using Domain-Specific Languages (DSLs) to Document API — the Kotlin DSL story Lana Novikova, Writerside, JetBrains
2. How it all started
3. Internal hackathon
4. What is a DSL? DSL programming language higher level of abstraction specific class of problems particular domain
5. 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
6. How it works
7. Simplistic documentation DSL val content = StardustDslContentProvider { p { +"Hello DSL"} list { li { +"List item 1" } li { +"List item 2" } } this } A paragraph A list
8. Simplistic documentation DSL
9. Simplistic documentation DSL val content = StardustDslContentProvider { table { tr { td { + "Parameter name" } td { + "Parameter type" } } tr { td { + "Value 1" } td { + "Value 2" } } this } A table
10. Simplistic documentation DSL
11. Simplistic documentation DSL xml(""" <procedure title="Title"> <step>Step 1</step> <step>Step 2</step> <step>Step 3</step> </procedure> """.trimIndent() ) Other language injection
12. Simplistic documentation DSL
13. Simplistic documentation DSL runConfigurations.forEach { runConfiguration -> chapter(id = runConfiguration.name, title = runConfiguration.name) { p { +runConfiguration.description} xml("""<include from="lib_fleet.xml" element-id="common-optional-properties"/>""") table(headerStyle = Table.HeaderStyle.NONE) { runConfiguration.properties.forEach { property -> tr { td { code { +property.key } } td { +property.value } } } } } } Combine the two
14. Simplistic documentation DSL
15. Did you just change the angle brackets to curly brackets?
16. It’s actually curly brackets and + No
17. 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
18. Separate data and its presentation
19. Separation of content and presentation Separation of content and presentation Separation of data and presentation Lightweight languages Kotlin DSL
21. Docs-as-code on a new level
22. Docs-as-code
23. Docs-are-code
24. Wait! Are you suggesting that the writer writes code now?
25. No, but it is good to have a choice Write docs using markup Extend it using code constructions
26. Use practices brought to us by developers • Refactorings • Completions • Dead code detection • Parameters/variables • Extracting into • Changing visibility
27. Time for demonstration
42. 546 API methods in total
43. The idea of generating HTML from code is not new
44. Why Kotlin?
45. 0. We are from JetBrains
46. 1. It is pragmatic and has a short learning curve
47. 2. Seamless integration with the JVM ecosystem
48. Extensibility
49. A few examples where (else) you can go:
50. 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
51. 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
52. 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
53. 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
54. 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 • Apply tests and assertions for autogenerated parts
55. Pitfalls
56. 1. You need to know what’s possible
57. 2. Flexibility leads to fragmentation
58. And one more thing
59. It helps you to start coding more smoothly I will help you learn Lambda functions variables conditionals nullable Extension functions
60. Thanks! Have a nice Kotlin DSL!
61. me { name = "Lana Novikova" twitter = "_Unsolved_" linkedin = "svetlana-novikova" } Come to the writerside
62. jetbrains.com Let’s stay in touch — @_Unsolved_ Come to the writerside @svetlnovikova https://www.linkedin.com/in/svetlana-novikova/