diff --git a/README.in b/README.in new file mode 100644 index 0000000..9a2b3b3 --- /dev/null +++ b/README.in @@ -0,0 +1,39 @@ + +## junreachable + +The `junreachable` package implements a set of exception types for +unambiguously marking code that is supposed to be unreachable (but that the +compiler cannot prove is unreachable). + +## Status + +As the Java platform evolves, libraries that may have been necessary in the +past can become unnecessary due to new platform features. The `junreachable` +package falls into this category: There are now far fewer instances in the +Java language where the compiler cannot determine that a given section of +code is unreachable. In particular, switch expressions and sealed types +eliminate many of the situations where unreachable code had to be explicitly +marked. + +This package is in maintenance mode and will not see any new functionality. + +## Features + +* Exceptions for marking unreachable code. +* High coverage test suite. +* [OSGi-ready](https://www.osgi.org/) +* [JPMS-ready](https://en.wikipedia.org/wiki/Java_Platform_Module_System) +* ISC license. + +## Usage + +Throw the `UnreachableCodeException` exception at lines of code that are +expected to be unreachable, but that the compiler cannot prove are really +unreachable. If this exception ends up being thrown, it will unambiguously +signal that the code wasn't as unreachable as the developer thought; this +is clearly a bug. + +Throw the `UnimplementedCodeException` exception at lines of code that have +yet to contain real implementations. If this exception ends up being thrown, +it is immediately clear to users and developers alike what happened: The user +tried to use some part of the code that hasn't yet been properly implemented. diff --git a/README.md b/README.md index 77a822e..c458fee 100644 --- a/README.md +++ b/README.md @@ -13,3 +13,43 @@ junreachable | OpenJDK (Temurin) LTS | Linux | [![Build (OpenJDK (Temurin) LTS, Linux)](https://img.shields.io/github/actions/workflow/status/io7m-com/junreachable/main.linux.temurin.lts.yml)](https://www.github.com/io7m-com/junreachable/actions?query=workflow%3Amain.linux.temurin.lts)| | OpenJDK (Temurin) Current | Windows | [![Build (OpenJDK (Temurin) Current, Windows)](https://img.shields.io/github/actions/workflow/status/io7m-com/junreachable/main.windows.temurin.current.yml)](https://www.github.com/io7m-com/junreachable/actions?query=workflow%3Amain.windows.temurin.current)| | OpenJDK (Temurin) LTS | Windows | [![Build (OpenJDK (Temurin) LTS, Windows)](https://img.shields.io/github/actions/workflow/status/io7m-com/junreachable/main.windows.temurin.lts.yml)](https://www.github.com/io7m-com/junreachable/actions?query=workflow%3Amain.windows.temurin.lts)| + +## junreachable + +The `junreachable` package implements a set of exception types for +unambiguously marking code that is supposed to be unreachable (but that the +compiler cannot prove is unreachable). + +## Status + +As the Java platform evolves, libraries that may have been necessary in the +past can become unnecessary due to new platform features. The `junreachable` +package falls into this category: There are now far fewer instances in the +Java language where the compiler cannot determine that a given section of +code is unreachable. In particular, switch expressions and sealed types +eliminate many of the situations where unreachable code had to be explicitly +marked. + +This package is in maintenance mode and will not see any new functionality. + +## Features + +* Exceptions for marking unreachable code. +* High coverage test suite. +* [OSGi-ready](https://www.osgi.org/) +* [JPMS-ready](https://en.wikipedia.org/wiki/Java_Platform_Module_System) +* ISC license. + +## Usage + +Throw the `UnreachableCodeException` exception at lines of code that are +expected to be unreachable, but that the compiler cannot prove are really +unreachable. If this exception ends up being thrown, it will unambiguously +signal that the code wasn't as unreachable as the developer thought; this +is clearly a bug. + +Throw the `UnimplementedCodeException` exception at lines of code that have +yet to contain real implementations. If this exception ends up being thrown, +it is immediately clear to users and developers alike what happened: The user +tried to use some part of the code that hasn't yet been properly implemented. + diff --git a/com.io7m.junreachable.documentation/pom.xml b/com.io7m.junreachable.documentation/pom.xml deleted file mode 100644 index ac387c3..0000000 --- a/com.io7m.junreachable.documentation/pom.xml +++ /dev/null @@ -1,214 +0,0 @@ - - - - 4.0.0 - - com.io7m.junreachable - com.io7m.junreachable - 4.0.1-SNAPSHOT - - com.io7m.junreachable.documentation - - jar - com.io7m.junreachable.documentation - Exception types for marking unreachable/unimplemented code (Documentation) - https://www.io7m.com/software/junreachable - - - true - - - - - ${project.groupId} - com.io7m.junreachable.core - ${project.version} - - - - com.io7m.primogenitor - com.io7m.primogenitor.support - - - - org.osgi - org.osgi.annotation.versioning - provided - - - org.osgi - org.osgi.annotation.bundle - provided - - - - - - - - org.apache.maven.plugins - maven-resources-plugin - - - copy-documentation-resources - - copy-resources - - generate-resources - - ${project.build.directory}/documentation/ - - - src/main/resources/com/io7m/junreachable/documentation/ - true - - - - - - - - - - org.apache.maven.plugins - maven-dependency-plugin - - - unpack-sources - package - - unpack-dependencies - - - module-info.java - ${project.groupId} - sources - false - ${project.build.directory}/javadoc-sources - - - - make-classpath - package - - build-classpath - - - ${project.build.directory}/javadoc-classpath - - - - - - - - com.io7m.jstructural - io7m-jstructural-maven-plugin - - - make-documentation-single - prepare-package - - transform - - - ${project.build.directory}/documentation/documentation.xml - ${project.build.directory}/documentation/ - ${project.build.directory}/documentation/brand.xml - XHTML_SINGLE - - - - make-documentation-multi - prepare-package - - transform - - - ${project.build.directory}/documentation/documentation.xml - ${project.build.directory}/documentation/ - ${project.build.directory}/documentation/brand.xml - XHTML_MULTI - - - - - - - - org.codehaus.mojo - exec-maven-plugin - - - javadoc - - java - - package - - com.io7m.primogenitor.support.TrivialJavadoc - - ${project.build.directory}/javadoc-sources - ${project.build.directory}/javadoc-classpath - ${project.build.directory}/documentation/apidocs - ${project.build.directory}/javadoc-log.txt - ${project.build.directory}/javadoc-options - - - - - - - - - org.apache.maven.plugins - maven-assembly-plugin - - - src/main/assembly/documentation.xml - - - - - make-assembly - package - - single - - - false - - - - - - - - - org.codehaus.mojo - truezip-maven-plugin - false - - - copy-site-documentation - - copy - - site - - true - - ${project.build.directory}/${project.name}-${project.version}.zip/${project.name}-${project.version}/ - ${project.parent.build.directory}/minisite/documentation/ - - - - - - - - - diff --git a/com.io7m.junreachable.documentation/src/main/assembly/documentation.xml b/com.io7m.junreachable.documentation/src/main/assembly/documentation.xml deleted file mode 100644 index 0b5d459..0000000 --- a/com.io7m.junreachable.documentation/src/main/assembly/documentation.xml +++ /dev/null @@ -1,21 +0,0 @@ - - documentation - ${project.name}-${project.version} - - zip - - - - ${project.build.directory}/documentation - / - - - ${project.build.directory}/site/apidocs - /apidocs - - - - diff --git a/com.io7m.junreachable.documentation/src/main/java/com/io7m/junreachable/documentation/Documentation.java b/com.io7m.junreachable.documentation/src/main/java/com/io7m/junreachable/documentation/Documentation.java deleted file mode 100644 index a48dd89..0000000 --- a/com.io7m.junreachable.documentation/src/main/java/com/io7m/junreachable/documentation/Documentation.java +++ /dev/null @@ -1,31 +0,0 @@ -/* - * Copyright © 2014 Mark Raynsford https://www.io7m.com - * - * Permission to use, copy, modify, and/or distribute this software for any - * purpose with or without fee is hereby granted, provided that the above - * copyright notice and this permission notice appear in all copies. - * - * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES - * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY - * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN - * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR - * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - */ - -package com.io7m.junreachable.documentation; - -import com.io7m.junreachable.UnreachableCodeException; - -/** - * Documentation marker class. - */ - -public final class Documentation -{ - private Documentation() - { - throw new UnreachableCodeException(); - } -} diff --git a/com.io7m.junreachable.documentation/src/main/java/com/io7m/junreachable/documentation/package-info.java b/com.io7m.junreachable.documentation/src/main/java/com/io7m/junreachable/documentation/package-info.java deleted file mode 100644 index 1f7b425..0000000 --- a/com.io7m.junreachable.documentation/src/main/java/com/io7m/junreachable/documentation/package-info.java +++ /dev/null @@ -1,21 +0,0 @@ -/* - * Copyright © 2014 Mark Raynsford https://www.io7m.com - * - * Permission to use, copy, modify, and/or distribute this software for any - * purpose with or without fee is hereby granted, provided that the above - * copyright notice and this permission notice appear in all copies. - * - * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES - * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY - * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN - * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR - * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - */ - -/** - * Documentation. - */ - -package com.io7m.junreachable.documentation; diff --git a/com.io7m.junreachable.documentation/src/main/java/module-info.java b/com.io7m.junreachable.documentation/src/main/java/module-info.java deleted file mode 100644 index e43cc33..0000000 --- a/com.io7m.junreachable.documentation/src/main/java/module-info.java +++ /dev/null @@ -1,26 +0,0 @@ -/* - * Copyright © 2014 Mark Raynsford https://www.io7m.com - * - * Permission to use, copy, modify, and/or distribute this software for any - * purpose with or without fee is hereby granted, provided that the above - * copyright notice and this permission notice appear in all copies. - * - * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES - * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY - * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN - * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR - * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - */ - -/** - * Documentation. - */ - -module com.io7m.junreachable.documentation -{ - requires com.io7m.junreachable.core; - - exports com.io7m.junreachable.documentation; -} \ No newline at end of file diff --git a/com.io7m.junreachable.documentation/src/main/resources/com/io7m/junreachable/documentation/brand.xml b/com.io7m.junreachable.documentation/src/main/resources/com/io7m/junreachable/documentation/brand.xml deleted file mode 100644 index c391a15..0000000 --- a/com.io7m.junreachable.documentation/src/main/resources/com/io7m/junreachable/documentation/brand.xml +++ /dev/null @@ -1,9 +0,0 @@ - -
-
- io7m -
-
- ${project.parent.name} ${project.version} -
-
\ No newline at end of file diff --git a/com.io7m.junreachable.documentation/src/main/resources/com/io7m/junreachable/documentation/documentation.css b/com.io7m.junreachable.documentation/src/main/resources/com/io7m/junreachable/documentation/documentation.css deleted file mode 100644 index 2b9cd43..0000000 --- a/com.io7m.junreachable.documentation/src/main/resources/com/io7m/junreachable/documentation/documentation.css +++ /dev/null @@ -1,63 +0,0 @@ -.brand -{ - font-size: 75%; - font-family: monospace; -} - -.brand_left -{ - float: left; -} - -.brand_right -{ - text-align: right; -} - -.package -{ - font-family: monospace; - font-weight: bold; -} - -.attribute, -.class, -.command, -.constant, -.element, -.file, -.function, -.keyword, -.type -{ - font-family: monospace; -} - -.example, .license, .terminal -{ - font-family: monospace; - border: 1px solid #ccc; - padding-top: 1.0em; - padding-left: 1.0em; - padding-bottom: 1.0em; - margin-top: 1.2em; - overflow: auto; -} - -.dependencies table td -{ - padding-right: 3.0em; - font-family: monospace; - font-size: 9pt; -} - -.platforms table td -{ - padding-right: 2.0em; -} -.platforms table tbody, -.platforms table thead -{ - font-size: 8pt; - font-family: monospace; -} diff --git a/com.io7m.junreachable.documentation/src/main/resources/com/io7m/junreachable/documentation/documentation.xml b/com.io7m.junreachable.documentation/src/main/resources/com/io7m/junreachable/documentation/documentation.xml deleted file mode 100644 index 855aa0d..0000000 --- a/com.io7m.junreachable.documentation/src/main/resources/com/io7m/junreachable/documentation/documentation.xml +++ /dev/null @@ -1,266 +0,0 @@ - - - - - - ${project.parent.name} ${project.version} Documentation - documentation.css - - - - Package Information - - - Orientation - - Overview - - The ${project.parent.name} package - implements a set of exception types for unambiguously marking code - that is supposed to be unreachable (but that the compiler cannot - prove is unreachable). - - - - - - Installation - - Source compilation - - The project can be compiled and installed with - Maven: - - - - - - - - Maven - - Regular releases are made to the - Central Repository, - so it's possible to use the ${project.parent.name} - package in your projects with the following Maven dependency: - - - - ${project.groupId} - ${project.parent.artifactId}-core - ${project.version} -]]> - - - All io7m.com - packages use Semantic Versioning - - http://semver.org - , which implies that it is always safe to use version ranges - with an exclusive upper bound equal to the next major version - the API of - the package will not change in a backwards-incompatible manner before the - next major version. - - - - - - Platform Specific Issues - - There are currently no known platform-specific issues. - - - - - License - - All files distributed with the ${project.parent.name} - package are placed under the following license: - http://io7m.com - -Permission to use, copy, modify, and/or distribute this software for any -purpose with or without fee is hereby granted, provided that the above -copyright notice and this permission notice appear in all copies. - -THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.]]> - - - - - - - Usage - - - Exceptions - - Unreachable - - The Java compiler typically cannot detect unreachable cases - in, for example, switch statements: - - - Unreachable switch - - - - The function f will fail to - compile due to a missing return - statement; even though all possible cases of - T are handled, the compiler is - not sufficiently intelligent to determine this. Naive developers - might try to add a default case, - but this makes the code fragile with respect to modification; if - someone adds an extra value to T, the - code silently becomes incorrect. The correct course of action is to - explicitly mark the unreachable code with an exception that unambiguously - states the intention: - - - Unreachable switch (fixed) - - - - The code now compiles. The code is robust in the face of later - modification of T. Anyone reading - the code understands that the original writer expected the code - to be unreachable. Anyone running the code and somehow managing - to reach the unreachable section is greeted with an unambiguous - exception that states that a bug has been discovered (and the - stack trace will indicate exactly where this happened). - - - - Unimplemented code - - Most Java development environments will automatically produce - empty method stubs when the programmer attempts to implement - an interface. The generated methods typically look something like: - - - Generated method stubs - - - - The programmer doesn't always have a complete implementation - ready immediately, and unfortunately nothing stops anyone from - running the as-yet unimplemented methods. The correct course of - action is to explicitly mark this unimplemented code with an - exception type that unambiguously states the nature of the code: - - - Generated method stubs (fixed) - - - - Discovering unimplemented code is now as simple as searching - for uses of UnimplementedCodeException - in the codebase. Anyone managing to execute unimplemented code will - be greeted with an exception that states exactly which code is - unimplemented. Most development environments can be instructed to - automatically generate code that throws - UnimplementedCodeException - exceptions as in the above example. - - - - - - - API Reference - - - Javadoc - - API documentation for the package is provided via the - included Javadoc. - - - - - diff --git a/pom.xml b/pom.xml index eeb60a2..9dccea7 100644 --- a/pom.xml +++ b/pom.xml @@ -23,7 +23,6 @@ com.io7m.junreachable.core com.io7m.junreachable.tests - com.io7m.junreachable.documentation @@ -113,13 +112,6 @@ - - - com.io7m.jstructural - io7m-jstructural-maven-plugin - 5.0.0 - - com.github.spotbugs diff --git a/src/site/resources/documentation.xml b/src/site/resources/documentation.xml index 5c0c663..c94a7c8 100644 --- a/src/site/resources/documentation.xml +++ b/src/site/resources/documentation.xml @@ -2,8 +2,7 @@

User documentation

- +

+ See the README. +