docs: ParselyTracker comments to Javadoc style #71
Conversation
| * To make sure all of the queued events are flushed to Parse.ly's servers, | ||
| * call this method in your main activity's `onDestroy()` method. |
There was a problem hiding this comment.
This is the only place I've modified the content slightly. Previous wording was confusing to me and was referencing the method it's commenting on, which, it seems, is not really correct in Javadoc convention:
|
@ParaskP7 just FYI - moving this PR to draft for now. I see other open source projects do share |
Even though it might not be completely neccessary as the SDK is open source, other open source libraries do share generated javadoc.jar files so we follow this convention.
|
👋 @wzieba !
Seems logical to me, thanks and yes, let's better share a PS: Let me know when you make this PR ready for review so I can take a look. |
Dokka, API documentation engine, needs more metaspace space than the default Gradle value (384m). Increasing it to 2g as suggested by authors.
| @@ -11,6 +11,7 @@ | |||
| # The setting is particularly useful for tweaking memory settings. | |||
| # Default value: -Xmx10248m -XX:MaxPermSize=256m | |||
| # org.gradle.jvmargs=-Xmx2048m -XX:MaxPermSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8 | |||
| org.gradle.jvmargs=-XX:MaxMetaspaceSize=2g | |||
There was a problem hiding this comment.
More on that: Kotlin/dokka#1405 (comment)
👍 @ParaskP7 the PR is now ready for review 🙂 |
wzieba
force-pushed
the
issue/51_update_comments_to_follow_javadoc
branch
from
7be7ebd
to
389186d
Compare
| * | ||
| * @param queue The list of event dictionaries to serialize | ||
| * @param events The list of event dictionaries to serialize |
There was a problem hiding this comment.
Praise (❤️): Nice catch! 🥇
| */ | ||
| //TODO: docs about where we get this UUID from and how. |
There was a problem hiding this comment.
Praise (❤️): Nicely done so as to not expose the TODO to be part of the documentation. 🥇
| @@ -26,6 +26,7 @@ android { | |||
| publishing { | |||
There was a problem hiding this comment.
Question (❓): I wonder whether we should migrate to publish-to-s3-gradle-plugin at some point and use the com.automattic.android.publish-to-s3 plugin instead, just like it is done for the rest of our libraries. 🤔
There was a problem hiding this comment.
That's a good question! When working on publishing of this library, I was considering our S3 instance but I decided to go with Maven Central because:
- Risk delegation
We delegate the risk of "out of service" incidents. If, by some reason, our S3 instance would go down, we would block building apps that use Parse.ly SDK.mavenCentralcan possibly go down as well, but then it won't be just Parse.ly SDK, but rather vast majority of every dependency clients' projects have 🙂
Other, less important reasons but still:
- Trust
MavenCentral is well known and trusted service for everyone working with Maven/Gradle projects. - Repository already included
ThemavenCentralrepository is already included in many projects, there's no reason to ask users to add a new repository. - Costs
(guessing) We possibly save costs of our S3 instance (less traffic).
I hope that this argumentation to use Maven Central makes sense!
There was a problem hiding this comment.
That all makes sense to me, thanks for the reply and for considering using the com.automattic.android.publish-to-s3 already @wzieba ! 🙇
Closes #51
Description
This PR updates convention of code comments from Doxygen (dropped in 1bb51a3) with Javadoc. The main benefit is convenience for library users in terms of viewing documentation for highlighted code. See here:
Not sharingjavadoc.jarI decided to not uploadSee #71 (comment)javadoc.jaras part of the artifact during the release because the source code of the SDK is open, so IDE will get comments directly from the source.How to test
parsely-3.0.8-javadoc.jarindex.htmlexist, and has comments. No need to check the content details.