Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lordofthejars/docstract


https://github.com/lordofthejars/docstract

Last synced: 26 days ago
JSON representation

Awesome Lists containing this project

README 

        
= Docstract



== What is it?



+docstract+ is an small +java+ project which reads a java source file, extracts the comments between +/**+ and +*/+ sequentially from all over the file and stores them inside an output +AsciiDoc+ file. The idea is not new in fact it is from https://github.com/javaee-samples/javaee7-samples/ developed by _Aslak Knutsen_ but instead of using +Ruby+ and inside +Awestruct+, this project is written in +java+ and it is run from CLI.



Let me show you an example to understand what this application does:



This is a class which contains some comments to be processed.



[source, java]

----

package com.lordofthejars.docstract;



/**

 * 

 * My name is *Alex*.

 * I am 33 years _old_.

 * 

 * Jump Jump +!!+.

 *

 * include::src/test/java/com/lordofthejars/asciidoctorfy/MyInterface.java[]

 *

 * include::src/test/java/com/lordofthejars/asciidoctorfy/Project#getId().java[]

 *

 */

public class MM {



	/**

	* It is a *method*.

	*/

	@Test

	public void method() {

		

		

	}

}

----



And the output document looks like:



....

My name is *Alex*.

I am 33 years _old_.



Jump Jump +!!+.



[source, java]

----

public interface MyInterface {



	void loginSuccess(Object hash);

	void loginSuccess();

	void foo(int number, Object block);

	

}

----



[source, java]

----

public String getId() {

	return id;

}

----



It is a *method*.

....



Note that in comments we are also using include macro for inserting files inside. The rules for inclusion are the next ones:



* if include contains a +java+ file, like first example, the whole class is read and inserted within AsciiDoc source code blocks.



* if include contains a +java+ file but with # symbol, like second one, the right part of # will be used as method name of given class. So for example +Project#setId(String, String)+ will include a method of Project's class called +setId+ and receiving two string parameters.



* if include contains an +xml+ file, the file is inserted "as is" within AsciiDoc source code block.



* if include contains an +xml+ file and between brackets there is an +xpath+ expression, the result of that expression will be inserted.



* any other include is left "as is", so it will be processed by +AsciiDoc(tor)+ processor.



Also note that the include files will be resolved relative from place where the CLI is being run, typically from the root of the project.



In case of using +xpath+ with namespaces you must register the namespace. So for example given a +pom.xml+ file, if we want to retrieve all dependencies with +groupId+ _junit_:



[source, java]

----

package com.lordofthejars.docstract;



/**

 *

 * include::src/test/resources/maven.xml[xmlns:mvn=http://maven.apache.org/POM/4.0.0 /mvn:project/mvn:dependencies/mvn:dependency[mvn:groupId[contains(., 'junit')]]]

 *

 *

 */

----



Where the first part (until first white space) is the delcaration of the namespace.



== Callouts



You can use callouts inside +java+ and +xml+ code and the processor will render it in the proper way.



In +java+ you can write a callout as a single line comment with callout number between _<,>_ at start.



[source, java]

----

public void code() {  

    System.out.println("Hello World"); // <1> Prints Hello World

}

----



In +xml+ you can write callouts between +xml+ comments and the callout number being the first word.



[source, xml]

----



    a 

    b

    c



----



Also you can use autonumerical feature so instead of setting the callout number for each line you can use the special character _#_, and then +docstract+ will assign it sequentially.



For example:



[source, java]

----

public void code() {  

    System.out.println("Hello World"); // <#> Prints Hello World

}

----



+docstract+ will replace the _#_ with the number 1. With +xml+ works as well.



WARNING: In case of useing +xpath+ expressions in +xml+ file, callouts don't work.   



== Download



You can grab a runnable jar from https://bintray.com/lordofthejars/generic/Docstract/0.2.0/view/files



== Usage



To render previous class we can call as:



....

java -jar docstract-.jar render --input=src/test/java/com/lordofthejars/asciidoctorfy/MM.java --output=README.adoc

....



And an +AsciiDoc+ file will be generated from comments blocks.



There is one optional parameter called +--baseDir+. This parameter is used to set the baseDir in include macros. So for example if you set baseDir to +/home/lotj/project+, the include macro will be resolved to +include::/home/lotj/project/src/test/java/....+.



== Live example



You can see an example at community _Tomitribe_ examples with class: https://github.com/tomitribe/community/blob/master/mongodb-example/src/test/java/org/superbiz/nosql/mongodb/GreetingsSessionBeanTest.java and the rendered output: https://github.com/tomitribe/community/blob/master/mongodb-example/README.adoc 



== Collaboration



New features will be added when they are required but of course feel free to clone and improve it.