You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by ma...@apache.org on 2018/04/03 17:20:32 UTC
[2/8] logging-log4j-kotlin git commit: Added Kotlin API documentation
Added Kotlin API documentation
These API docs are heavily based on the Scala API docs.
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j-kotlin/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j-kotlin/commit/42458fd5
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j-kotlin/tree/42458fd5
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j-kotlin/diff/42458fd5
Branch: refs/heads/master
Commit: 42458fd54ff98a1d13ebba5db519278d6c1c083b
Parents: bb2e89d
Author: Raman Gupta <ro...@gmail.com>
Authored: Mon Apr 2 20:24:24 2018 -0400
Committer: Raman Gupta <ro...@gmail.com>
Committed: Mon Apr 2 20:45:22 2018 -0400
----------------------------------------------------------------------
src/main/asciidoc/build.adoc | 26 ++++++++
src/main/asciidoc/changes.adoc | 27 ++++++++
src/main/asciidoc/contributing.adoc | 66 +++++++++++++++++++
src/main/asciidoc/download.adoc | 69 ++++++++++++++++++++
src/main/asciidoc/index.adoc | 44 +++++++++++++
src/main/asciidoc/usage.adoc | 107 +++++++++++++++++++++++++++++++
6 files changed, 339 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j-kotlin/blob/42458fd5/src/main/asciidoc/build.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/build.adoc b/src/main/asciidoc/build.adoc
new file mode 100644
index 0000000..cf7eca5
--- /dev/null
+++ b/src/main/asciidoc/build.adoc
@@ -0,0 +1,26 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+== Building From Source
+
+NOTE: The following information is for developers who wish to modify Log4j Kotlin API or contribute.
+If your goal is to add logging to your application, then you can use the link:build.html[pre-built binaries] instead.
+
+.Building
+[source,bash]
+----
+mvn package
+----
http://git-wip-us.apache.org/repos/asf/logging-log4j-kotlin/blob/42458fd5/src/main/asciidoc/changes.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/changes.adoc b/src/main/asciidoc/changes.adoc
new file mode 100644
index 0000000..3c5b19b
--- /dev/null
+++ b/src/main/asciidoc/changes.adoc
@@ -0,0 +1,27 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+== ChangeLog
+
+=== Version 1.0
+
+[vertical]
+New Features::
+[horizontal]
+LOG4J2-1705::: Initial release
+
+[vertical]
+Bug Fixes:: None.
http://git-wip-us.apache.org/repos/asf/logging-log4j-kotlin/blob/42458fd5/src/main/asciidoc/contributing.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/contributing.adoc b/src/main/asciidoc/contributing.adoc
new file mode 100644
index 0000000..4730d54
--- /dev/null
+++ b/src/main/asciidoc/contributing.adoc
@@ -0,0 +1,66 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+== Contributing
+
+You have found a bug or you have an idea for a cool new feature?
+Contributing code is a great way to give something back to the open source community.
+Before you dig right into the code there are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.
+
+=== Getting Started
+
+* Make sure you have a https://issues.apache.org/jira/[Jira account].
+* Make sure you have a https://github.com/signup/free[GitHub account].
+* If you're planning to implement a new feature it makes sense to discuss your changes on the https://logging.apache.org/log4j/2.x/mail-lists.html[dev list] first.
+ This way you can make sure you're not wasting your time on something that isn't considered to be in Apache Log4j's scope.
+* Submit a ticket for your issue, assuming one does not already exist.
+ * Clearly describe the issue including steps to reproduce when it is a bug.
+ * Make sure you fill in the earliest version that you know has the issue.
+* Fork the repository on GitHub.
+
+=== Making Changes
+
+* Create a topic branch from where you want to base your work (this is usually the master branch).
+* Make commits of logical units.
+* Respect the original code style:
+ * Only use spaces for indentation.
+ * Create minimal diffs - disable on save actions like reformat source code or organize imports.
+ If you feel the source code should be reformatted create a separate PR for this change.
+ * Check for unnecessary whitespace with `git diff --check` before committing.
+* Make sure your commit messages are in the proper format.
+ Your commit message should contain the key of the Jira issue.
+* Make sure you have added the necessary tests for your changes.
+* Run all the tests with `sbt "+ test"` to assure nothing else was accidentally broken.
+
+=== Making Trivial Changes
+
+For changes of a trivial nature to comments and documentation, it is not always necessary to create a new ticket in JIRA.
+In this case, it is appropriate to start the first line of a commit with '(doc)' instead of a ticket number.
+
+=== Submitting Changes
+
+* Sign the https://www.apache.org/licenses/#clas[Contributor License Agreement] if you haven't already.
+* Push your changes to a topic branch in your fork of the repository.
+* Submit a pull request to the repository in the apache organization.
+* Update your Jira ticket and include a link to the pull request in the ticket.
+
+=== Additional Resources
+
+* https://issues.apache.org/jira/browse/LOG4J2[Apache Log4j 2 Jira project page]
+* https://www.apache.org/licenses/#clas[Contributor License Agreement]
+* https://help.github.com/[General GitHub documentation]
+* https://help.github.com/send-pull-requests/[GitHub pull request documentation]
+
http://git-wip-us.apache.org/repos/asf/logging-log4j-kotlin/blob/42458fd5/src/main/asciidoc/download.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/download.adoc b/src/main/asciidoc/download.adoc
new file mode 100644
index 0000000..08ec948
--- /dev/null
+++ b/src/main/asciidoc/download.adoc
@@ -0,0 +1,69 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+== Download
+
+Apache Log4j Kotlin API is distributed under the https://www.apache.org/licenses/LICENSE-2.0.html[Apache License, version 2.0].
+The link in the Mirrors column should display a list of available mirrors with a default selection based on your inferred location.
+If you do not see that page, try a different browser.
+The checksum and signature are links to the originals on the main distribution server.
+
+|===
+|Distribution |Mirrors |Signature
+
+|Apache Log4j Kotlin API binary (tar.gz)
+|TODO
+|TODO
+
+|Apache Log4j Kotlin API binary (zip)
+|TODO
+|TODO
+
+|Apache Log4j Kotlin API source (tar.gz)
+|TODO
+|TODO
+
+|Apache Log4j Kotlin API source (zip)
+|TODO
+|TODO
+|===
+
+It is essential that you verify the integrity of the downloaded files using the PGP or MD5 signatures.
+Please read https://httpd.apache.org/dev/verification.html[Verifying Apache HTTP Server Releases] for more information on why you should verify our releases.
+
+The PGP signatures can be verified using PGP or GPG.
+First download the https://www.apache.org/dist/logging/KEYS[KEYS] as well as the asc signature file for the relevant distribution.
+Make sure you get these files from the https://www.apache.org/dist/logging/[main distribution directory], rather than from a mirror.
+Then verify the signatures using:
+
+[source,bash,subs=attributes]
+----
+gpg --import KEYS
+gpg --verify apache-log4j-kotlin-{project-version}-bin.tar.gz.asc apache-log4j-kotlin-{project-version}-bin.tar.gz
+gpg --verify apache-log4j-kotlin-{project-version}-bin.zip.asc apache-log4j-kotlin-{project-version}-bin.zip
+gpg --verify apache-log4j-kotlin-{project-version}-src.tar.gz.asc apache-log4j-kotlin-{project-version}-src.tar.gz
+gpg --verify apache-log4j-kotlin-{project-version}-src.zip.asc apache-log4j-kotlin-{project-version}-src.zip
+----
+
+Log4j Kotlin API requires https://logging.apache.org/log4j/2.x/download.html[Log4j API].
+
+=== Using Gradle
+
+TODO
+
+=== Using Maven
+
+TODO
http://git-wip-us.apache.org/repos/asf/logging-log4j-kotlin/blob/42458fd5/src/main/asciidoc/index.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc
new file mode 100644
index 0000000..811782e
--- /dev/null
+++ b/src/main/asciidoc/index.adoc
@@ -0,0 +1,44 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+= Apache Log4j Kotlin API
+:toc: left
+
+Log4j Kotlin API is a https://kotlinlang.org/[Kotlin] logging facade based on https://logging.apache.org/log4j/2.x/[Log4j 2].
+
+Log4j Kotlin API uses Log4j 2.x as its logging backend.
+
+Log4j Kotlin API uses Log4j 2.x as its logging backend by default, but this can also be replaced with compatible libraries (e.g., https://logback.qos.ch/[Logback]).
+
+While this library is not required to use Log4j API in Kotlin, it does provide idiomatic Kotlin APIs which are friendlier to use in Kotlin programs than the Java APIs.
+
+include::usage.adoc[]
+
+include::download.adoc[]
+
+include::changes.adoc[]
+
+include::build.adoc[]
+
+include::contributing.adoc[]
+
+////
+TODO:
+* Apache logo
+* License report
+* Project links
+* Dependency report
+////
http://git-wip-us.apache.org/repos/asf/logging-log4j-kotlin/blob/42458fd5/src/main/asciidoc/usage.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/usage.adoc b/src/main/asciidoc/usage.adoc
new file mode 100644
index 0000000..5a40074
--- /dev/null
+++ b/src/main/asciidoc/usage.adoc
@@ -0,0 +1,107 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+== Usage
+
+Using the Kotlin API is as simple as mixing in the https://github.com/apache/logging-log4j-kotlin/blob/master/log4j-api-kotlin/src/main/kotlin/org/apache/logging/log4j/kotlin/Logging.kt[`Logging`] interface to your class. Example:
+
+[source,kotlin]
+----
+import org.apache.logging.log4j.kotlin.Logging
+
+class MyClass: BaseClass, Logging {
+ fun doStuff() {
+ logger.info("Doing stuff")
+ }
+ fun doStuffWithUser(user: User) {
+ logger.info { "Doing stuff with ${user.name}." }
+ }
+}
+----
+
+The `Logging` interface can also be mixed into `object` declarations, including companions.
+
+[source,kotlin]
+----
+import org.apache.logging.log4j.kotlin.Logging
+
+class MyClass: BaseClass {
+ companion object : Logging {
+ // other declarations
+ }
+
+ ...
+}
+----
+
+Alternatively, a more traditional style can be used to instantiate a logger instance:
+
+[source,kotlin]
+----
+import org.apache.logging.log4j.kotlin
+
+class MyClass: BaseClass {
+ val logger = logger()
+
+ ...
+}
+----
+
+The function `logger()` is an extension function on the `Any` type (or more specifically, any type `T` that extends `Any`).
+
+=== API Documentation
+
+See https://logging.apache.org/TODO[KDocs].
+
+=== Configuration
+
+Log4j Kotlin API uses https://logging.apache.org/log4j/2.x/manual/configuration.html[Log4j configuration] by default.
+
+This supports XML, properties files, and Java-based builders, as well as JSON and YAML with additional dependencies.
+
+=== Substituting Parameters
+
+Unlike Java, Kotlin provides native functionality for https://kotlinlang.org/docs/reference/basic-syntax.html#using-string-templates[string templates].
+
+However, using a string template still incurs the message construction cost if the logger level is not enabled. To avoid this, prefer passing a lambda which won't be evaluated until necessary.
+
+For example:
+
+[source,kotlin]
+----
+logger.debug { "Logging in user ${user.name} with birthday ${user.calcBirthday()}" }
+----
+
+=== Logger Names
+
+Most logging implementations use a hierarchical scheme for matching logger names with logging configuration.
+
+In this scheme the logger name hierarchy is represented by '.' characters in the logger name, in a fashion very similar to the hierarchy used for Java/Kotlin package names.
+
+The `Logger` property added by the `Logging` interface follows this convention: the interface ensures the `Logger` is automatically named according to the class it is being used in.
+
+The value returned when calling the `logger()` extension method depends on the receiver of the extension. When called within an Object as shown above, the receiver is `this` and therefore the logger will again be named according to the class it is being used in. However, a logger named via another class can be obtained as well:
+
+[source,kotlin]
+----
+import org.apache.logging.log4j.kotlin
+
+class MyClass: BaseClass {
+ val logger = SomeOtherClass.logger()
+
+ ...
+}
+----