New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Meta Kdocs Playgrounds #1202

Merged
merged 74 commits into from Dec 18, 2018

Conversation

Projects
None yet
3 participants
@raulraja
Copy link
Member

raulraja commented Dec 15, 2018

The following PR brings the ability to project KDoc executable code examples from type classes into their instances automatically generating concrete runnable snippets on each of the projected extensions:

ank_extensions

Additionaly it includes:

  • :ank:playground. Allows executable snippets that automatically are rendered as playgrounds
  • :ank:playground:extension. Used to document type classes that project code examples to their instances.
  • Functor.void -> Functor.unit. because files named void are ignored in javadocs by Dokka.
  • Fixes #1163 incorrect projection of kinded values with arity > 2

raulraja and others added some commits Dec 4, 2018

`@documented` allows `@extension` instances to skip projection of kdo…
…cs from their type classes

This is useful for cases such as `Cofree` `Free` where we can't easily project values that would create compilable snippets
Merge remote-tracking branch 'origin/master' into rr-meta-kdoc
# Conflicts:
#	modules/core/arrow-annotations/src/main/java/arrow/hks.kt
#	modules/core/arrow-data/src/test/kotlin/arrow/data/OptionTTest.kt
#	modules/streams/arrow-streams/src/main/kotlin/arrow/streams/internal/instances.kt
Revised Ank runtime to display heap numbers again now that there are …
…many more code snippets to process and compile.
domlopez
domlopez

raulraja added some commits Dec 17, 2018

raulraja and others added some commits Dec 17, 2018

@raulraja raulraja requested a review from arrow-kt/maintainers Dec 18, 2018

data class Field(val msg: String)

private fun map(list: List<Validated<NonEmptyList<NetworkCorruptedField>, Field>>): Validated<NonEmptyList<NetworkCorruptedField>, List<Field>> {
val errorList = ArrayList<NetworkCorruptedField>()

This comment has been minimized.

@pakoito

pakoito Dec 18, 2018

Member

mutableListOf() so it's idiomatic Kotlin :D

fun String.quote(): String =
split(".").joinToString(".") {
if (KotlinReservedKeywords.contains(it)) "`$it`"
else it
}

This comment has been minimized.

@pakoito

pakoito Dec 18, 2018

Member

Extra endline :p

@pakoito
Copy link
Member

pakoito left a comment

A couple of nits, LGTM!

@@ -62,6 +62,11 @@ allprojects {
delete pathApiDocs
}

//attempt to reduce travis memory constrains
tasks.withType(Test) {

This comment has been minimized.

@nomisRev

nomisRev Dec 18, 2018

Member

Does this work? And should we leave this?

This comment has been minimized.

@raulraja

raulraja Dec 18, 2018

Member

Yes, forks tests and reduces memory consumption

@@ -207,7 +207,7 @@ operator fun <K, V> Map<out K, V>.plus(tuples: Array<out Tuple2<K, V>>): Map<K,
operator fun <K, V> Map<out K, V>.plus(tuples: Sequence<Tuple2<K, V>>): Map<K, V> =
LinkedHashMap(this).apply { putAll(tuples) }.optimizeReadOnlyMap()

inline fun <K, V> Map.Entry<K, V>.toTuple2(): Tuple2<K, V> = Tuple2(key, value)
fun <K, V> Map.Entry<K, V>.toTuple2(): Tuple2<K, V> = Tuple2(key, value)

This comment has been minimized.

@nomisRev
@@ -251,3 +251,26 @@ class ValidatedTest : UnitSpec() {
}
}
}

data class NetworkCorruptedField(val msg: String)

This comment has been minimized.

@nomisRev

nomisRev Dec 18, 2018

Member

Left overs?


/**
* ank_macro_hierarchy(arrow.typeclasses.Functor)
*
* The [Functor] type class abstracts the ability to `map` over the computational context of a type constructor.

This comment has been minimized.

@nomisRev

nomisRev Dec 18, 2018

Member

I am not sure if there is a convention about this, or if we want to introduce a convention for this in the Arrow docs but normally I always link to the corresponding methods. Even if they occur multiple times in the same doc snippet.

I notice you've only done this for the first occurrence and not for the map function.

This comment has been minimized.

@raulraja

raulraja Dec 18, 2018

Member

What would that look like in this example? GitHub suggestion please 😘

This comment has been minimized.

@nomisRev

nomisRev Dec 18, 2018

Member

AFAIK it's not possible to do multiline GitHub suggestion, right?

@raulraja raulraja merged commit 65e429e into master Dec 18, 2018

4 checks passed

ci/bitrise/b4ac6a91e50a5bdd/pr Passed - arrow
Details
ci/bitrise/b4ac6a91e50a5bdd/push Passed - arrow
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
continuous-integration/travis-ci/push The Travis CI build passed
Details

@raulraja raulraja deleted the rr-meta-kdoc branch Dec 18, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment