Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

Lana
June 05, 2023

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

Lana

June 05, 2023
Tweet

More Decks by Lana

Other Decks in Technology

Transcript

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

    View full-size slide

  2. How it all started

    View full-size slide

  3. Internal
    hackathon

    View full-size slide

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

    View full-size slide

  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

    View full-size slide

  6. How it works

    View full-size slide

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

    View full-size slide

  8. Simplistic documentation DSL

    View full-size slide

  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

    View full-size slide

  10. Simplistic documentation DSL

    View full-size slide

  11. Simplistic documentation DSL
    xml("""

    Step 1
    Step 2
    Step 3

    """.trimIndent()
    )
    Other
    language
    injection

    View full-size slide

  12. Simplistic documentation DSL

    View full-size slide

  13. 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

    View full-size slide

  14. Simplistic documentation DSL

    View full-size slide

  15. Did you just change the angle brackets
    to curly brackets?

    View full-size slide

  16. It’s actually curly brackets and +
    No

    View full-size slide

  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

    View full-size slide

  18. Separate data and its
    presentation

    View full-size slide

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

    View full-size slide

  20. Docs-as-code on a new
    level

    View full-size slide

  21. Docs-as-code

    View full-size slide

  22. Docs-are-code

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  26. Time for demonstration

    View full-size slide

  27. 546 API methods in total

    View full-size slide

  28. The idea of generating HTML from code
    is not new

    View full-size slide

  29. 0. We are from JetBrains

    View full-size slide

  30. 1. It is pragmatic and has a short
    learning curve

    View full-size slide

  31. 2. Seamless integration with the JVM
    ecosystem

    View full-size slide

  32. Extensibility

    View full-size slide

  33. A few examples where (else) you can go:

    View full-size slide

  34. 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

    View full-size slide

  35. 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

    View full-size slide

  36. 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

    View full-size slide

  37. 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

    View full-size slide

  38. 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

    View full-size slide

  39. 1. You need to know what’s possible

    View full-size slide

  40. 2. Flexibility leads to fragmentation

    View full-size slide

  41. And one more thing

    View full-size slide

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

    View full-size slide

  43. Thanks!
    Have a nice Kotlin DSL!

    View full-size slide

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

    View full-size slide

  45. jetbrains.com
    Let’s stay in touch

    @_Unsolved_
    Come to the
    writerside
    @svetlnovikova
    https://www.linkedin.com/in/svetlana-novikova/

    View full-size slide