Better documentation

fugerit-org · Aug 21, 2024 · fee6809 · fee6809
1 parent 52c9dba
commit fee6809
Show file tree

Hide file tree

Showing 2 changed files with 25 additions and 0 deletions.
diff --git a/fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/project/facade/AddVenusFacade.java b/fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/project/facade/AddVenusFacade.java
@@ -32,6 +32,8 @@ private AddVenusFacade() {}
 
     private static final String EXAMPLE_FOLDER = "config/example/";
 
+    private static final String LINE = "************************************************************************************************************************";
+
     private static void addDocFacade( VenusContext context ) throws IOException, TemplateException, ConfigException {
         // freemarker configuration
         Configuration configuration = new Configuration( new Version( FreeMarkerConfigStep.ATT_FREEMARKER_CONFIG_KEY_VERSION_LATEST ) );
@@ -94,6 +96,7 @@ public static boolean addVenusToMavenProject( VenusContext context ) {
                 addExtensionList( pomFile, context );
                 if ( context.isAddDocFacace() ) {
                     addDocFacade( context );
+                    log.info( "Generation complete:\n{}\n* For usage open the example main() : {} *\n{}", LINE, context.getDocConfigPackage()+"."+context.getDocConfigClass()+"Example", LINE );
                 }
             } else {
                 addErrorAndLog( String.format( "No pom file in project dir : %s", pomFile.getCanonicalPath() ), context );

diff --git a/fj-doc-maven-plugin/src/main/resources/config/example/DocHelperExample.java b/fj-doc-maven-plugin/src/main/resources/config/example/DocHelperExample.java
@@ -10,20 +10,42 @@
 import java.util.Arrays;
 import java.util.List;
 
+/**
+ * This is a basic example of Fugerit Venus Doc usage,
+ * running this main the program will :
+ * - creates data to be used in document model
+ * - renders the 'document.ftl' template
+ * - print the result in markdown format on the stanndard output
+ *
+ * For further documentation :
+ * https://github.com/fugerit-org/fj-doc
+ *
+ * NOTE: This is a 'Hello World' style example, adapt it to your scenario, especially :
+ *  - remove system out and system err with your logging system
+ *  - change the doc handler and the output mode (here a ByteArrayOutputStream buffer is used)
+ */
 public class DocHelperExample {
 
     public static void main(String[] args) {
         try ( ByteArrayOutputStream baos = new ByteArrayOutputStream() ) {
+            // creates the doc helper
             DocHelper docHelper = new DocHelper();
+            // find the handler for the output :
             DocTypeHandler docTypeHandler = docHelper.getDocProcessConfig().getFacade().findHandler(DocConfig.TYPE_MD);
+            // create custom data for the fremarker template 'document.ftl'
             List<People> listPeople = Arrays.asList( new DocHelperExample.People( "Luthien", "Tinuviel", "Queen" ), new DocHelperExample.People( "Thorin", "Oakshield", "King" ) );
+            // output generation
             docHelper.getDocProcessConfig().fullProcess( "document", DocProcessContext.newContext( "listPeople", listPeople ), docTypeHandler, DocOutput.newOutput( baos ) );
+            // print the output
             System.out.println( "html output : \n"+ new String( baos.toByteArray(), StandardCharsets.UTF_8 ) );
         } catch (Exception e) {
             e.printStackTrace();
         }
     }
 
+    /*
+     * Class used to wrap data to be rendered in the document template
+     */
     public static class People {
 
         private String name;