Skip to content

Latest commit

 

History

History
119 lines (71 loc) · 4.59 KB

gist-taglet-description.md

File metadata and controls

119 lines (71 loc) · 4.59 KB
Raw

Description of the Gist Markdown Taglet ({{gist ...}})

Embedding a gist within your javadoc as (highlighted) code.

The gist markdown taglet resolve the content of a gist from Github and render this to an highlighted code block. A single gist contains at least one gist file.

Benefits

  • So using this markdown taglet it's easier to share code examples.
  • When somebody find an issue with your code example, he can make a comment, directly to your gist.
  • Fixing issue is easier.
  • You can write full examples including javadoc comments /** ... */.
  • Annotations is no issue anymore.
  • The raw code is reachable with one click and .

Remarks

  • This taglet not a javadoc taglet. It's a markdown taglet.

  • The gist markdown taglet is a standard markdown taglet. So you don't need add it to the doclet.

  • A markdown taglet is extension to the pegdown-doclet.

  • It's possible to write your own markdown taglet

  • and adding it by -mdtaglet <my markdown taglet>.

Syntax

{{**gist** _option(s)_ **_gist-id_** _file(s)_}}
{%**gist** _option(s)_ **_gist-id_** _file(s)_%}
{$**gist** _option(s)_ **_gist-id_** _file(s)_$}

  • gist-id: This is the hexadecimal identification of a public gist.

  • files(s): select the gist file(s) to be rendered. If your gist has more then one gist file, you can select one or more of them. If you do not provide a selector, all files of your gist will be rendered.

  • option(s): the rendering options. You can set up to 2 optional options which overwrites the general settings.

    • +indent/-indent: enable/disable indent (default is enabled).
    • +desc/-desc: enable/disable rendering the gist's description (default is enabled)

Markdown Taglet Options (-mdt-)

The markdown taglet options are parameters to the javadoc tool. If any of the options produce an error the default value will be used.

Rendering options

  • -mdt-gist-indent: Enable or disable the indent rendering of the gist.

    • Possible values are true/false
    • Default is true

  • -mdt-gist-description: Enable or disable the rendering of the gist's description.

    • Possible values are true/false
    • Default is true

Github API options

The gist markdown taglet make heavy use of the Github API using GitHub API for Java. So this taglet does not work without access to Github.

  • -mdt-gist-github-properties: Provide a property file with credentials for the Github API.

    • If you do not provide your own property file, the taglet tries to find ~/.github
    • or if none is available, use anonymous mode.
    • Remarks:
      1. If you don't provide your own credentials, you can run in Github rate limits: Currently 60 request per hour.
      2. I recommend using oauth=<any token>.
      3. Visit Github - Creating an access token

  • -mdt-gist-github-use-cache: Enable or disable the use of an cache

    • Possible values are true/false
    • Default is true
    • Only of the cache is enabled the other cache related options have an effect.

  • -mdt-gist-github-cache-size: Set the cache size in MB

    • The default value is 10 MB
    • Only values > 0 are valid

  • -mdt-gist-github-cache-dir: Set a cache directory.

    • This is only the parent directory. The actually cache directory will be <directory>/mdt-gist-cache
    • The default is either ./target or ./build, if neither could be found ./cache will be created.
    • So using the default cache settings with Maven/Gradle the cache will also dropped, if you call for example gradle clean.
    • Even using the cache does not prevent from calling the Github API, but there should be no issue with the Github rate limits.

Examples

{{gist feafcf888d949627001948b8346e0da7}} 
    - renders all gist files


{{gist feafcf888d949627001948b8346e0da7 GistTest.java}}   
    - renders only GistTest.java of the gist
    
{{gist feafcf888d949627001948b8346e0da7 'GistTest.java'}} 
    - same result (useful if your filename contains whitespace characters)


{{gist -desc feafcf888d949627001948b8346e0da7}} 
    - do not render the gist's description