{"id":23578593,"url":"https://github.com/dnault/therapi-runtime-javadoc","last_synced_at":"2025-04-09T21:19:22.658Z","repository":{"id":5740836,"uuid":"41772834","full_name":"dnault/therapi-runtime-javadoc","owner":"dnault","description":"Read Javadoc comments at run time.","archived":false,"fork":false,"pushed_at":"2023-10-30T20:05:25.000Z","size":420,"stargazers_count":126,"open_issues_count":9,"forks_count":20,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-09T21:19:15.418Z","etag":null,"topics":["annotation-processor","javadoc","javadoc-comments","javadocs","runtime"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dnault.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-09-02T01:37:43.000Z","updated_at":"2025-03-25T01:19:16.000Z","dependencies_parsed_at":"2025-01-06T12:32:19.672Z","dependency_job_id":"7c82bfe8-5302-4e7e-802c-11836243b7e3","html_url":"https://github.com/dnault/therapi-runtime-javadoc","commit_stats":{"total_commits":196,"total_committers":10,"mean_commits":19.6,"dds":"0.19897959183673475","last_synced_commit":"629fa89f4b264b61f046fee80357e3145d810a1d"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnault%2Ftherapi-runtime-javadoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnault%2Ftherapi-runtime-javadoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnault%2Ftherapi-runtime-javadoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnault%2Ftherapi-runtime-javadoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dnault","download_url":"https://codeload.github.com/dnault/therapi-runtime-javadoc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248111973,"owners_count":21049578,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotation-processor","javadoc","javadoc-comments","javadocs","runtime"],"created_at":"2024-12-26T22:39:41.556Z","updated_at":"2025-04-09T21:19:22.635Z","avatar_url":"https://github.com/dnault.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# therapi-runtime-javadoc\n\n![Java 1.8+](https://img.shields.io/badge/java-1.8+-lightgray.svg)\n\n\n## Bake Javadoc comments into your code\n\n1. Add an annotation processor to your class path at compile time.\n2. Read Javadoc comments at run time.\n\nThe annotation processor copies Javadoc from your source code\ninto class path resources.\n\nThe runtime library reads the class path resources, serving up your\nJavadoc on demand.\n\n\n## Coordinates\n\n### Gradle\n\n```groovy\ndependencies {\n    annotationProcessor 'com.github.therapi:therapi-runtime-javadoc-scribe:0.13.0'\n\n    // Runtime library\n    implementation 'com.github.therapi:therapi-runtime-javadoc:0.13.0'\n}\n```\n\n### Maven\n\n```xml\n\u003c!-- Annotation processor --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.therapi\u003c/groupId\u003e\n    \u003cartifactId\u003etherapi-runtime-javadoc-scribe\u003c/artifactId\u003e\n    \u003cversion\u003e0.13.0\u003c/version\u003e\n    \u003cscope\u003eprovided\u003c/scope\u003e\n\u003c/dependency\u003e\n    \n\u003c!-- Runtime library --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.therapi\u003c/groupId\u003e\n    \u003cartifactId\u003etherapi-runtime-javadoc\u003c/artifactId\u003e\n    \u003cversion\u003e0.13.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n\n## Usage\n\n### Building a JAR with embedded Javadoc\n\nInclude the annotation processor JAR in your class path when compiling\nthe code whose Javadoc you want to read later at runtime. \n\nWhen building in an IDE you may have to explicitly enable annotation processing.\nIn IntelliJ this is done by going to \n`Preferences \u003e Build, Execution, Deployment \u003e Compiler \u003e Annotation Processors`\nand checking the box labeled \"Enable annotation processing\".\n\n\n#### Selective Retention\n\nIf you only want to retain the Javadoc from certain packages, use the\n`-A` javac argument to pass the `javadoc.packages` option to the annotation\nprocessor. The value is a comma-delimited list of packages whose Javadoc\nyou want to keep. (Subpackages are included, recursively.)\n    \nFor Gradle that might look like this:\n\n```groovy\ntasks.withType(JavaCompile) {            \n  options.compilerArgs \u003c\u003c \"-Ajavadoc.packages=com.example,org.example\"\n}\n```\n\nIf you don't specify any packages, the default behavior is to retain Javadoc\nfrom all packages.\n\n\n### Reading Javadoc comments at runtime\n\nAdd the runtime library as a dependency of your project.\n\nRead the Javadoc by calling `RuntimeJavadoc.getJavadoc` and passing a\nclass literal, a fully-qualified class name, or a `java.lang.reflect.Method`.\nBecause Javadoc comments may contain inline tags, you'll want to use a\n`CommentFormatter` to convert comments to strings.\n\nHere's an example that prints all available documentation for a class:\n\n```java\nimport com.github.therapi.runtimejavadoc.*;\nimport java.io.IOException;\n\npublic class Example {\n    // formatters are reusable and thread-safe\n    private static final CommentFormatter formatter = new CommentFormatter();\n\n    public static void printJavadoc(String fullyQualifiedClassName) throws IOException {\n        ClassJavadoc classDoc = RuntimeJavadoc.getJavadoc(fullyQualifiedClassName);\n        if (classDoc.isEmpty()) { // optionally skip absent documentation\n            System.out.println(\"no documentation for \" + fullyQualifiedClassName);\n            return;\n        }\n\n        System.out.println(classDoc.getName());\n        System.out.println(format(classDoc.getComment()));\n        System.out.println();\n\n        // @see tags\n        for (SeeAlsoJavadoc see : classDoc.getSeeAlso()) {\n            System.out.println(\"See also: \" + see.getLink());\n        }\n        // miscellaneous and custom javadoc tags (@author, etc.)\n        for (OtherJavadoc other : classDoc.getOther()) {\n            System.out.println(other.getName() + \": \" + format(other.getComment()));\n        }\n\n        System.out.println();\n        System.out.println(\"CONSTRUCTORS\");\n        for (MethodJavadoc methodDoc : classDoc.getConstructors()) {\n            printMethodJavadoc(methodDoc);\n        }\n\n        System.out.println();\n        System.out.println(\"METHODS\");\n        for (MethodJavadoc methodDoc : classDoc.getMethods()) {\n            printMethodJavadoc(methodDoc);\n        }\n    }\n\n    private static void printMethodJavadoc(MethodJavadoc methodDoc) {\n        System.out.println(methodDoc.getName() + methodDoc.getParamTypes());\n        System.out.println(format(methodDoc.getComment()));\n        \n        if (!methodDoc.isConstructor()) {\n            System.out.println(\"  returns \" + format(methodDoc.getReturns()));\n        }\n\n        for (SeeAlsoJavadoc see : methodDoc.getSeeAlso()) {\n            System.out.println(\"  See also: \" + see.getLink());\n        }\n        for (OtherJavadoc other : methodDoc.getOther()) {\n            System.out.println(\"  \" + other.getName() + \": \"\n                + format(other.getComment()));\n        }\n        for (ParamJavadoc paramDoc : methodDoc.getParams()) {\n            System.out.println(\"  param \" + paramDoc.getName() + \" \"\n                + format(paramDoc.getComment()));\n        }\n        for (ThrowsJavadoc throwsDoc : methodDoc.getThrows()) {\n            System.out.println(\"  throws \" + throwsDoc.getName() + \" \"\n                + format(throwsDoc.getComment()));\n        }\n        System.out.println();\n    }\n\n    private static String format(Comment c) {\n        return formatter.format(c);\n    }\n}\n```\n\n## License\n\n```\nCopyright 2015 David Nault and contributors\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n\n## Notice\n\nThis software includes the following libraries,\nrepackaged to avoid potential dependency conflicts:\n\n* [minimal-json](https://github.com/ralfstx/minimal-json)\n  (MIT License) Copyright (c) 2013, 2014 EclipseSource\n\n* [JavaPoet](https://github.com/square/javapoet)\n  (Apache 2.0 License) Copyright (c) 2015 Square, Inc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnault%2Ftherapi-runtime-javadoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdnault%2Ftherapi-runtime-javadoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnault%2Ftherapi-runtime-javadoc/lists"}