https://github.com/codenameone/javadocsourceembed
Allows embedding github gist's int JavaDoc in a way that works with code completion
https://github.com/codenameone/javadocsourceembed
Last synced: 11 months ago
JSON representation
Allows embedding github gist's int JavaDoc in a way that works with code completion
- Host: GitHub
- URL: https://github.com/codenameone/javadocsourceembed
- Owner: codenameone
- Created: 2016-01-15T17:41:12.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2023-04-14T17:23:38.000Z (almost 3 years ago)
- Last Synced: 2025-01-28T05:41:52.606Z (about 1 year ago)
- Homepage: https://www.codenameone.com/blog/javadoc-source-samples-that-dont-suck.html
- Size: 429 KB
- Stars: 6
- Watchers: 2
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# JavaDoc Source Embed
JavaDoc is a wonderful tool with some annoying limitations, one of them is its inability to handle source code embeds.
[Githubs gist](http://gist.github.com/) is an amazing tool for embeding source code but it requires JavaScript which means
it doesn't work with the popups in common IDE's and isn't as searchable.
Gist makes source embedding trivial since you can embed a single sample in multiple methods/classes and manage the sample
itself in a centeral location.
Which makes it look like this: https://www.codenameone.com/javadoc/com/codename1/location/LocationManager.html
With JavaScript enabled you see this:
Without JavaScript (or in IDE/search engine) you will see this:
Those screenshots were generated by this javadoc, notice that all the source comes from [this gist](https://gist.github.com/codenameone/b0fa5280bde905a8f0cd):
```java
/**
*
The LocationManager is the main entry to retrieveLocation or to bind a LocationListener, important: in
* order to use location on iOS you will need to define the build argument ios.locationUsageDescription.
* This build argument should be used to describe to Apple & the users why you need to use the location
* functionality.
*
* Usage:
*
*/
public abstract class LocationManager {
```
When you generate JavaDoc it queries github for the gist contents and embeds it as a ``
alternative right into the code. This means IDE code completion will "just work" as it will have a sensible fallback.
Just pass the source directory and an output directory to the jar file and then generate the javadoc based on the output
directory.
E.g:
```bash
rm -Rf dist/javadoc
rm -Rf build/tempJavaSources
java -jar JavaDocSourceEmbed-1.0-SNAPSHOT.jar pathToSrcDir/src build/tempJavaSources
javadoc -protected -d dist/javadoc -windowtitle "Codename One API" build/tempJavaSources
```
> **Important**: notice that we use a temporary directory to generate the source and don't generate to the original directory. The reason for that is simple. If you change the gist or add additional gists in the future youd want them to be updated.
Or using ant you can do something like:
```xml
```