lunes, enero 27, 2014

DRY with examples on documentation. Include Java Extension for Asciidoctor.


One of the great features that Asciidoctor offers us as a writers of manuals, tutorials and documentation in general is that allows us to follow the DRY pattern. If for example you are writing a tutorial, probably you will have one part of the tutorial which will be the documentation, and another part which will be source code with examples. Asciidoctor allows us to write the documentation and include the examples directly from source code project to document.

For example:


As you can see you can include directly from source code the example and Asciidoctor will render it inside the document. Moreover if you set the language, Asciidoctor will highlight the code too.

But as you can see there is one problem with this approach, you are including the whole file, with imports, javadoc, comments, ... and maybe you only want to show a method of that class. Now with Asciidoctor you have two options:

Using lines attribute:

Which have the problem that modifying original source code also modifies the code embedded inside tutorial.

Using tags:

Which is an invasive method that requires you modify the original source code:


But now we have got another option in case your language is Java. And it is using java-semantic-asciidoctorj extension. This extension allows us to embed parts of the code by its components. That is you can set which method to add, which class, if you want to add imports or not, ... The extension only works with asciidoctorj-1.5.0.preview1 and beyond, and uses the new SPI for extensions, so you only have to add the jar extension on classpath, and the extension is automatically registered.

An example of usage of this extension could be the next one. Let's imagine that we have a class with 5 methods and we want to include only a method called mymethod which receives an String as parameter and it has no return value. Also we want to add the imports, but nothing else.

We could do something like:

Note that now we are not invading our code with comment-tags, nor fixing the position with lines of the method inside our document.

The attributes you can set in include are:
  • imports: adds the imports.
  • fields: adds the fields of the main class.
  • class: adds all the content of the main class.
  • enum=<classname>: adds the enum with the given name. The enum should be defined inside the class we are adding.
  • annotation=<classname>: same as enum but for annotations.
  • class=<classname>: same as enum but for inner classes.
  • contructor=<constructorName>(<parameterType1>,<parameterType2>, ....): adds the defined constructor. In this case we must set the constructor name and the type of each parameter. For example: MyClass(String).
  • method=<returnType> <methodName>(<parameterType1>, <parameterType2>, ...): same as constructor but for methods, which implies adding the return type. Note that it is not required to add any modifier nor throws classes.

Now we can use our classes within our documentation and by adding the required block.

This version of plugin works with Java 1.7 and before, not with Java 1.8 but it could work in some cases.

The extension is published on bintray, so to install you simply have to add bintray repository and the required dependency:

The project is hosted at: https://github.com/lordofthejars/asciidoctorj-extensions

We keep learning,
Alex.
I feel shouting ya-hoo, And me still feeling hungry, Cowabunga!!, Cookie monster went and ate the new red two. Monster Went and Ate My Red 2 - Elvis Costello & Elmo
Music: https://www.youtube.com/watch?v=KxardpBReQc

7 comentarios:

yanmaneee dijo...

timberlands
louboutin shoes
off white hoodie
jordan 6
nike 95
moncler coat
vapormax
hermes
cheap nba jerseys
air max 270

Michael Jones dijo...

These online sources can be useful in making your assignments and projects immediately. There are many online assignment help services which can make your work easier. It will lessen your burden, and you can focus more on your studies and other activities.Online Assignment help

Programming Assignment help

hpprintercare dijo...

When you encounter an issue printer is in an error statethen there is a problem with HP printer itself. Hence, check your printer first before wasting your crucial time in wandering for reliable assistance. Check the network connection, ink level, paper loaded into the input tray, and many more internal things. If all is ok and still encountering the same error problem, then now the time turn to dial toll-free number which is mention here. One of our tech-savvy will instantly connect to you over phone call and give you the right information so that effortlessly you will be able to troubleshoot the printer in error state issue. https://www.hpprintersupportpro.com/blog/facing-issue-hp-printer-in-error-state-connect-with-out-experts/

filingbazaar dijo...

Filing Bazaar is one of the best destination to apply online for Class 3 Digital Signature in Delhi. A digital signature certifies the identify of person and sender of mail and message. A class 3 digital signature offers the high level of security and assurance. Contact experts to apply for a class 3 digital signature.https://www.filingbazaar.com/service/class-3-dsc-delhi-

rickypauls dijo...

Assignment Help services offers quality and plagiarism-free work for students to acquire good grades on their subjects. If you are about to miss your due dates, login to greatassignmenthelp and complete your work on time.
Assignment Help Online
Online Assignment Help
Assignment Help Online Services
Assignment Helper
Assignment Assistance
Assignment Help Experts
Online Assignment Help Services

James Marcus dijo...

Oh! Great Topic lovely writing. Please keep posting some related blogs. Visit our Outlook blog, if you need any type of Outlook help. You may also dial Microsoft outlook support number for the quick support.
How do I contact Microsoft tech support?”
How do I contact Microsoft Outlook support
Is there a phone number for Outlook support
Outlook support

Canon Support dijo...

Get Methods to Connect Canon Printer To Wi-Fi From Experts
For getting printed documents and pictures effortlessly, Canon Printer Offline would be the top-most choice as it offers hands-free printing services to the customers. It has many ultimate features, including its all; you can also print or scan wirelessly with this printing machine. But before do print job wirelessly, you have to Canon printer and also make sure that the required software drivers and applications are installed on the computer system as only then you will be applicable to Connect Canon Printer To Wi-Fi. In case, finding any difficulties in order to performing this task, then make a cold conversation to our all day all night presented tech-specialists. Toll-free number is there to unite with us, so call us as soon as possible.
canon setup
Canon error code 5b00
Canon B200 Error
Canon Wireless Printer Setup
Connect Canon Printer To Wi-Fi
Canon printer offline
canon pixma mx490
canon ts3122
canon printer reset
Canon Printer Setup