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

41 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

IT dijo...

The effectiveness of IEEE Project Domains depends very much on the situation in which they are applied. In order to further improve IEEE Final Year Project Domains practices we need to explicitly describe and utilise our knowledge about software domains of software engineering Final Year Project Domains for CSE technologies. This paper suggests a modelling formalism for supporting systematic reuse of software engineering technologies during planning of software projects and improvement programmes in Project Centers in Chennai for CSE.

Spring Framework has already made serious inroads as an integrated technology stack for building user-facing applications. Spring Framework Corporate TRaining the authors explore the idea of using Java in Big Data platforms.
Specifically, Spring Framework provides various tasks are geared around preparing data for further analysis and visualization. Spring Training in Chennai

Robert Duvall dijo...

To bring your HP printer setup, you need to give a click at 123.hp.com by opening a web browser on your computer system. The effectual and hands-free solution is there, you only have to follow the guidelines as mentioned on that page. Once you reach to the bottom of the page, you will see your HP printer has been setup. Be careful while downloading and installing printer driver and software as during this setting up process in case the network gets lost, your printer won’t setup properly and might create some problems during print job.

garminmapgpsupdates dijo...

If you’re facing issues to update Garmin GPS, we can help you immediately. How to update Garmin GPS? Our Garmin experts have rich experience and depth knowledge to update Garmin GPS in the right ways. Our Garmin experts are sitting 24/7 to guide you step by step for updating Garmin GPS in the right ways.
Garmin Gps Update
Garmin Gps Updates
Garmin Map Update
Garmin Map Updates
Update garmin gps
How to update garmin gps
Garmin updater
Garmin map update free
Garmin Updates
Garmin.com/express
Garmin Express

Online Technical Help dijo...

Very nice!!! This is really good blog information thanks for sharing. We are independent third party specialists to resolve the software issues dial toll free +1-800-642-7676 and Get support click here
Microsoft Office 365 Support
Microsoft Support Number
Outlook Support Phone Number
Is there a phone number for outlook support?
How can I contact outlook customer service?
Is there a phone number for Microsoft outlook support?
How Do I Contact Microsoft Office 365 Support?
How do I contact Outlook Support?
Is there a Phone Number for Office 365 Support?

Microsoft Outlook Office dijo...

Whenever your Windows gives you one error or the countless, you just need to grab Windows support. The available professionals of this support are well-educated and always ready to give their best. I am telling you all this because I have experienced all of these. So, when on Earth you need to resolve your issues associated with Windows, then I personally suggest you to make connection with the Microsoft windows support team’s professionals.
Website:- https://www.microsoftoutlookoffice.com/windows-support-number
How do I contact Microsoft Office Support?
Is there a phone number for Microsoft office support?
Is there a Phone Number for Office 365 Support?
office 365 Support
Microsoft office 365 support
outlook keeps asking for password
Microsoft outlook keeps asking for password
Outlook Working Offline
Microsoft Outlook Working Offline
Outlook 2016 Working Offline
Is there a phone number for Outlook support?
How do I contact Microsoft Outlook support?
How do I call Outlook support?
How to get Outlook Support Phone Number?

Microsoft Support dijo...

This is the very first time I called and grabbed Microsoft Support with the intention of eliminating my Microsoft issues. The professional who answered my call is very friendly in nature as well as helpful in resolving problem. He step-wisely guided me to terminate my entire issues and didn’t leave me until my entire glitches are resolved. So, I would advise everyone that whenever you face Microsoft issues, then grab this support.
Website:- https://www.microsoftoutlooksupportnumber.com/
outlook Support Number
outlook Support Phone number
outlook Support
Microsoft outlook Support
How do I contact outlook by phone?
How do I contact Microsoft Outlook support?
How do I call Outlook support?
Is there a phone number for Outlook support?
How to get Outlook Support Phone Number?

printersupportnumber dijo...

Nice post. Very helpful. Visit HP Support for any Technical issue. Regarding Laptop, Printers etc HP Products.

Katelyn Leah dijo...

Let us help you to execute canon.com/ijsetup. The device setup manual will have the necessary instructions. Switch on your printer to proceed to activate the network. If the wireless direct method is available, enable it to activate the connection automatically. Now update the software visiting the canon software download page. It’s time to use the toll-free number and speak to our techies for more guidance

allprinterrepair dijo...

The HP printer series comes with the HP Smart app which is the brains of the printer. You can use this app for printing documents from your device that has the smart app as long as it is on the same network. You could schedule certain jobs, you could edit the documents you want to print, and much more Visit our blog HP Printer Troubleshooting

123.hp.com dijo...

123.hp.com/dj3630 |
hp deskjet 3630 how to scan |
123.hp.com/dj3630 install |
HP Deskjet 3630 driver |
123.hp.com/setup |
123.hp.com |
123hpsetup |
123.hp.com setup |
123hp.comsetup |
www.123.hp.com/setup |
123hp |
123.hp |
123 hp |
123.hp.com |
123.hp.com |
123.hp.com | Call Us+1-888-863-4264 |

devodson dijo...

Do you want to have a candid discussion with highly experienced and skilled technicians who are capable of providing the reliable solution to your Yahoo Mail Login problems? Here, what you are needed to do is to avail the customer care services directly geeks who have great troubleshooting experience and proficiency in fixing such problems in no time.

andrerushell dijo...

If you are willing to set up Cashtag for the purpose of availing unlimited benefits, it would be recommended to avail Cash App Customer Service in which you will be able to share your problems with the experienced techies and also ask for the help and guidance regarding anything pertaining to cash app.

Unknown dijo...

How Do I Fix Sending/Receiving Problems With Gmail Customer Service?
Due to several reasons, you might face several sorts of problems which can happen at any point of the time. Users might also face problems in sending or

receive mails and look for the help. In such a case, you should take Gmail

Customer Service
and get the rid of all the complex problems in no time.

Unknown dijo...

Take Advice From Gmail Customer Service Before Begin With Fixing Your Problems
Before you begin with troubleshooting of any kind of Gmail related problems on your own, you should make sure you are going to make use of the right

technical steps. However, you should also take proper guidance along with the supervision of professionals at Gmail Customer Service in a couple of seconds.

Unknown dijo...

Mend Gmail Not Responding Problems With Gmail Customer Service
To fix Gmail not responding problems, you will have to take necessary solution to your problems with optimum ease. Here, you can get rid of all the reasons

causing such problems to you but the required technical step must be taken under the supervision of experts who are live at Gmail Customer Service .

Unknown dijo...

Unblock The Blocked Person On Gmail By Taking Gmail Support Service
Do you want to unblock the persons that you have mistakenly blocked? For that, you will have to take the required troubleshooting assistance directly from

the professionals who will provide you with the instructions that you need to implement for unblocking that person. Take Gmail Support if needed for advice.

Unknown dijo...

Take Gmail Help And Support For Getting Yourself Out From Critical Situation
Are you in such a critical situation while working on Gmail? Do you want to be acquainted with the troubleshooting solution to your problems pertaining to

your Gmail? For that, you should take proper Gmail Help directly from the

professionals who would help you to get rid of all your hurdles in a couple of seconds.

Unknown dijo...

Exterminate Server Problem With Protocol Issues Via Gmail Phone Number
Are you facing server problem with outgoing as well as incoming protocols during the course of accessing Google mail account? Do you want to get them sorted

out as quickly as possible with permanent resolution? In such a case, you should make use of Gmail Phone Number at anytime from anywhere.

celina disuza dijo...

Safeguard Your Facebook Privacy With Facebook Support
As there are numerous intruders and cyber terrorists available over the internet hunting different online account for negative purposes, you should also be safe while on Facebook. In order to keep you account secured that no one can even breach your privacy,
you should take Facebook Support which would be available 24 hours a day. https://www.phonesupportnumbers.net/facebook-customer-service/

celina disuza dijo...

Applicable On Facebook Know Via Facebook Phone Number
Do you want to know the types of names applicable on Facebook that each user can make use separately? By taking reliable and real time guidance on Facebook, you should make use of Facebook Phone Number and get the proper information about what you are looking forward.
https://customer-carenumber-usa.com/facebook-customer-service/

celina disuza dijo...

Effectively Deal With Facebook Username Related Problems at Facebook Number
Aren’t you aware of the quick fix solution to deal with your Facebook username related problems? There are some certain criteria under which you can create your username for your Facebook account.
Hence, you should know about the same and for that, you can also fetch the supervision using Facebook Number.
https://email-how.com/facebook-customer-service-phone-number-troubleshoot/

logansah dijo...


How Does Facebook Customer Service Help To Create Facebook Account?
Creating Facebook account allows you to stay in touch with your loved ones. In addition to this, Facebook also enables the users to accomplish personal or professional works efficiently. To set up account on Facebook, you should be acquainted with the procedure of the same. Just avail Facebook Customer Service! https://www.my-accountrecovery.com/facebook-customer-service/

logansah dijo...


Facebook Customer Service: How To Add Mobile Number To Facebook?
Adding number to your Facebook account will help you to get your lost Facebook account password, hacked account or compromised account back with ease. The problem is that you are not capable of adding your phone number. For that, you should fetch the guidance at Facebook Customer Service. https://www.customercare-email.net/facebook-customer-service/

logansah dijo...


Get To Know About Process To Set Up Business Account With Facebook Support
If you are searching for the guidance to set up business account so that you could cater your professional needs with ease, you should make use of the best possible solution using Facebook Support at anytime and fetch the proper assistance directly from Facebook certified connoisseurs. https://www.technicalsupportphonenumber.com/facebook-customer-service-number/

Lanedavis dijo...

How Do I Change Facebook Password Using Facebook Phone Number?
You don’t need to worry about the password changing problems. If you want to update your Facebook account password, you should make use of Facebook Phone Number and get to know the default procedure via which you can get rid of the obstacles you confront when it comes to changing or resetting password.https://www.numbersfor-support.com/facebook-customer-service-number/

Lanedavis dijo...

Acquire Live Customer Support At Facebook Number For Feasible Security Tips
Are you searching for reliable customer support so that you could fetch the feasible security tips and measures for the effective improvement of your social media account? You can use Facebook Number at anytime and get the right guidance from the connoisseurs regarding the security measures and suggestions. https://www.customer-service-phonenumber.com/facebook-customer-service-number/

Lanedavis dijo...

Facebook Glitches Now Avoidable Via Facebook Help At Anytime
Are you looking for reliable Facebook Help? For that, you should visit to official help center of Facebook and search for the problems you are encountering while on Facebook. Once you enter your issues, you will come across the different links containing the real time troubleshooting instructions that you need to implement. https://www.getcustomerservice.org/facebook-customer-service/

Unknown dijo...

Gmail Customer Service: An Immediate Aid For Storage Problems
Make use of Gmail Customer Service right now and share the storage related problems with the professionals you have approached through the above mode. Whether it is technical inconvenience or any complex mishap causing storage related hurdles, you will surely resolve all your problems with optimum ease.

Unknown dijo...

Check Out The Gmail Customer Service Facility For Gmail Drive Problems
Are you facing problems with the Gmail drive? Are you not capable of accessing Gmail Drive in order to safekeeping of any essential data, emails and documents? The Gmail Customer Service is the round the clock working facility that one can avail for the purpose of fixing such problems from the root.

Unknown dijo...


Take Gmail Support Service If Unable To Chat On Hangouts
You are not required to take stress or worry about the problems you face when it comes to chatting with any of your friends on Gmail hangouts. Whenever such problems take place, consider taking Gmail Support Service would be the right decision and also provides you with the dependable solution in no time.

Unknown dijo...

Doorstep Gmail Support Service Now Coming At Cost Effective Service Charges
You don’t need to have a financial burden while availing the best in class Gmail Support service as the charge of availing the same service is very low and can be availed at anytime from anywhere. Round the clock availability of such support service will help to have a hassle free experience on Gmail.

Unknown dijo...

Grab Reasonable Technical backing at Gmail Phone Number
Are you stuck during the course of repairing the problematic Google mail account? In such a critical case, you should avoid the problems due to which you have been facing a lot of hurdles and obstacles. For the best resolution, you can try using Gmail Phone Number at anytime from anywhere in the world.

Unknown dijo...

Mitigate Complex Security Shortcomings And Loopholes By Using Gmail Phone Number
Do you want to put all Gmail security hurdles aside? For that, you can avail technical support by just making use of Gmail Phone Number and the all your loopholes and shortcomings sorted out within a few seconds. Here, safety tips would also be given so that you could safeguard your Google mail account.

Unknown dijo...

How Does Gmail Help To Create New Label For Emails?
Are you completely unable to create new label for your Google mail account? Are you worried just because of the same? In such a case, you should quickly approach the industrious professionals using Gmail Help and support service and opt for the reliable possible backing in a couple of seconds.