java - Is there a way to embed the contents of a file or partial file in javadoc -


when write unit tests, see them both mechanism of verifying code behaves intended , documented examples of how use code. such, love include contents of test classes examples. this:

/**  * foos bar  * @example foobartest#testfooingbar()  * @param bar {@link bar} foo  * return fooed {@code bar}  */ public bar foobar(bar bar) {    // foo bar }

then when gets rendered 1 see content of foobartest.testfooingbar() in javadoc.

i did googling , didn't see anything. there way can (maven plugin perhaps)?

i've finished beta version of library this. it's called codelet. here's answer posted in this question:

this question i've tried answer codelet (github link).

codelet automates insertion of already unit-tested example code javadoc, using taglets. taglets, codelet executed part of javadoc.exe. released in beta, (and needs beta testers!).

there 4 codelet taglets:

  • {@codelet.and.out}: displays source code followed output
  • {@codelet}: displays source code only
  • {@codelet.out}: displays output only
  • {@file.textlet}: displays contents of plain-text file, such input example code.

a common example:

{@.codelet.and.out com.github.aliteralmind.codelet.examples.adder.adderdemo%eliminatecommentblocksandpackagedecl()}

which uses eliminatecommentblocksandpackagedecl() "customizer" eliminate package declaration line , multi-line comments (such license , javadoc blocks).

output (between horizontal rules):

example

public class adderdemo  {    public static final void main(string[] ignored)  {        adder adder = new adder();       system.out.println(adder.getsum());        adder = new adder(5, -7, 20, 27);       system.out.println(adder.getsum());    } }

output

0 45

an alternative display portion of example's code: code snippet:

{@.codelet.and.out com.github.aliteralmind.codelet.examples.adder.adderdemo%linerange(1, false, "adder adder", 2, false, "println(adder.getsum())", "^ ")}

this displays same example above, starting (the line containing) adder adder, , ending second println(adder.getsum()). eliminates indentation, in case 6 spaces.

output (between horizontal rules):

example

adder adder = new adder(); system.out.println(adder.getsum());  adder = new adder(5, -7, 20, 27); system.out.println(adder.getsum());

output:

0 45

all taglets accept customizers.

it possible write own customizers which, example, can "linkify" function names, change template in source-and-output displayed, , arbitrary alteration or lines. examples include highlighting in yellow, or making regular expression replacements.

as final example, , contrast above, here taglet blindly prints lines example code, without changes. uses no customizer:

{@.codelet.and.out com.github.aliteralmind.codelet.examples.adder.adderdemo}

output (between horizontal rules):

example

/*license*\    codelet: copyright (c) 2014, jeff epstein (aliteralmind __dash__ github __at__ yahoo __dot__ com)     software dual-licensed under the:    - lesser general public license (lgpl) version 3.0 or, @ option, later version;    - apache software license (asl) version 2.0.     either license may applied @ discretion. more information may found @    - http://en.wikipedia.org/wiki/multi-licensing.     text of both licenses available in root directory of project, under names &quot;license_lgpl-3.0.txt&quot; , &quot;license_asl-2.0.txt&quot;. latest copies may downloaded at:    - lgpl 3.0: https://www.gnu.org/licenses/lgpl-3.0.txt    - asl 2.0: http://www.apache.org/licenses/license-2.0.txt \*license*/ package  com.github.aliteralmind.codelet.examples.adder; /**    <p>demonstration of {@code com.github.aliteralmind.codelet.examples.adder.adder}.</p>     <p>{@code java com.github.aliteralmind.codelet.examples.adderdemo}</p>     @since  0.1.0    @author  copyright (c) 2014, jeff epstein ({@code aliteralmind __dash__ github __at__ yahoo __dot__ com}), dual-licensed under lgpl (version 3.0 or later) or asl (version 2.0). see source code details. <a href=&quot;http://codelet.aliteralmind.com&quot;>{@code http://codelet.aliteralmind.com}</a>, <a href=&quot;https://github.com/aliteralmind/codelet&quot;>{@code https://github.com/aliteralmind/codelet}</a>  **/ public class adderdemo  {    public static final void main(string[] ignored)  {        adder adder = new adder();       system.out.println(adder.getsum());        adder = new adder(5, -7, 20, 27);       system.out.println(adder.getsum());    } }

output:

0 45

codelet in beta, reasonably stable. please consider giving try, , giving comments , criticisms in github issue tracker.

thanks.


Comments

Post a Comment

Popular posts from this blog

android - Get AccessToken using signpost OAuth without opening a browser (Two legged Oauth) -

i using signpost oauth access data magento server. have read various tutorials on same , reach point open browser user can enter credentials. however, per requirement have automate part. hence, user should not browser page. have set-up done on server side ( magento ), hit url , returned call page. same through program in android. i have tried below, consumer = new commonshttpoauthconsumer(key, secret); provider = new commonshttpoauthprovider(oauth_init_url,access_token_url, authorize_url); try { provider.retrieverequesttoken(consumer, oauth.out_of_band); log.d("tokens" , consumer.gettoken() + " -- " + consumer.gettokensecret()); } and request tokens. dont know how bypass next step. tried directly accessing accesstoken (stupid of me) provider.retrieveaccesstoken(consumer, "mycallback://callback"); no luck, ends in oauth.signpost.exception.oauthnotauthorizedexception: authorization failed (server replied 401). ...
Read more

org.mockito.exceptions.misusing.InvalidUseOfMatchersException: mockito -

getting error org.mockito.exceptions.misusing.invaliduseofmatchersexception: invalid use of argument matchers! 1 matchers expected, 2 recorded. exception may occur if matchers combined raw values: //incorrect: somemethod(anyobject(), "raw string"); when using matchers, arguments have provided matchers. example: //correct: somemethod(anyobject(), eq("string matcher")); at when( getprogramservice .callservice(any(getprogramtype.class))) .thenreturn(jaxbresponse); please explain error , possible resolution the code posted looks fine; don't see problem it. code before or above causing exception. key here: invalid use of argument matchers! 1 matchers expected, 2 recorded. any , used above, doesn't return "special kind of null" or "special kind of getprogramtype"; don't exist. instead, returns null , side effect puts matcher on stack. whe...
Read more

google shop client API returns 400 bad request error while adding an item -

i'm working on solution add items in google shopping market java application. following tutorial real mess because of missing classes of laste release, after setting 1.5-beta maven managed make base example typecheck correctly classes. still can make simple task of adding 1 item. instead of posting whole code i'm posting part creates product feed. private product createproduct(string id) { product product = new product(); product.title = "red wool sweater"; product.content = new content( "text", "comfortable , soft, sweater keep warm on " + "cold winter nights. red , blue stripes."); product.appcontrol = new appcontrol(); product.appcontrol.addrequireddestination("productads"); product.externalid = id; product.lang = "it"; product.country = "it"; product.condition = "nuovo"; product.price = new price("eu...
Read more