Improve documentation of the calculation parser, tree parser and the qqueue messages

core/src/main/scala/eu/nomad_lab/QueueMessage.scala

@@ -4,6 +4,8 @@ import eu.nomad_lab.parsers.ParseResult.ParseResult
 import org.json4s.JsonAST.{JArray, JString, JField, JObject}
 import org.json4s._
 
+/** Enum of possible tree/archive type
+  */
 object TreeType extends Enumeration {
   type TreeType = Value
   val File, Directory, Zip, Tar, Unknown = Value
@@ -13,7 +15,7 @@ class InvalidTreeTypeException(
                                 msg: String, what: Throwable = null
                               ) extends Exception(msg, what)
 
-/** Json serialization to and deserialization support for MetaInfoRecord
+/** Json serialization and deserialization support for MetaInfoRecord
   */
 class TreeTypeSerializer extends CustomSerializer[TreeType.Value](format => (
   {
@@ -31,6 +33,8 @@ class TreeTypeSerializer extends CustomSerializer[TreeType.Value](format => (
 
 object QueueMessage {
 
+  /** Request sent to the tree parser to find the appropriate parser for the given tree/archive
+    */
   case class TreeParserRequest(
                                      treeUri: String, // URI inside the given treeFilePath; eg. nmd://R9h5Wp_FGZdsBiSo5Id6pnie_xeIH/data
                                      treeFilePath: String, //Path to the archive or the root directory eg. /nomad/nomadlab/raw_data/data/R9h/R9h5Wp_FGZdsBiSo5Id6pnie_xeIH.zip
@@ -40,6 +44,8 @@ object QueueMessage {
                                      followSymlinks: Boolean = true // In case of directory
                                    )
 
+  /** Request send to the calculation parser to uncompress the tree/archive and initialize the parser
+    */
   case class CalculationParserRequest(
                                        parserName: String, //Name of the parser to use for the file; CastepParser
                                        mainFileUri: String, //Uri of the main file; Example:  nmd://R9h5Wp_FGZdsBiSo5Id6pnie_xeIH/data/examples/foo/Si2.castep
@@ -49,6 +55,8 @@ object QueueMessage {
                                        overwrite: Boolean = false // Overwrite an existing file; eg. In case of failure of previous run
                                      )
 
+  /** Result of the calculation parser.
+    */
   case class CalculationParserResult(
                                          parseResult:ParseResult,
                                          parserInfo: JValue, // info on the parser used i.e. {"name":"CastepParser","version":"1.0"}
@@ -60,6 +68,8 @@ object QueueMessage {
                                          parseRequest: CalculationParserRequest//Uri of the main file; Example:  nmd://R9h5Wp_FGZdsBiSo5Id6pnie_xeIH/data/examples/foo/Si2.castep
                                          )
 
+  /** Result of the calculation parser to be normalized.
+    */
   case class ToBeNormalizedQueueMessage(
                                      parserInfo: JValue, // info on the parser used i.e. {"name":"CastepParser","version":"1.0"}
                                      mainFileUri: String, //Uri of the main file; Example:  nmd://R9h5Wp_FGZdsBiSo5Id6pnie_xeIH/data/examples/foo/Si2.castep
@@ -67,7 +77,9 @@ object QueueMessage {
                                      parsedFilePath: String // Complete file path, to the parsed file /nomad/nomadlab/work/parsed/<parserId>/Put/PutioKaDl4tgPd4FnrdxPscSGKAgK.nc
                                    )
 
-  case class NormalizedQueueMessage(
+  /** The final normalized result.
+    */
+  case class NormalizedResult(
                                      normalizedFileUri: String, // This is build as sha of archive, changing R into N, i.e. nmd://N9h5Wp_FGZdsBiSo5Id6pnie_xeIH
                                      normalizedFilePath: String // Complete file path, to the normalized file /nomad/nomadlab/normalized/<parserId>/N9h/N9h5Wp_FGZdsBiSo5Id6pnie_xeIH.nc
                                    )

core/src/main/scala/eu/nomad_lab/parsers/ParserRun.scala

@@ -8,9 +8,11 @@ import com.typesafe.scalalogging.StrictLogging
 
 object ParserRun extends StrictLogging {
 
-  /* Parse the given file path with the given parser and options
-  *
-  * */
+  /** Parse the given file path with the given parser and options
+  * @param parserGen: Parser generator to create the optimized parser to use.
+  * @param pPath: Path of the file to Parse
+  * @param opt: Backend type of the parsed file
+  */
   def parse(parserGen: SimpleExternalParserGenerator,pPath:String,opt:String): ParseResult.Value =
   {
     object BackendType extends Enumeration {

core/src/main/scala/eu/nomad_lab/parsing_queue/CalculationParser.scala

@@ -16,7 +16,16 @@ import eu.{nomad_lab => lab}
 import scala.collection.mutable
 import scala.util.control.NonFatal
 
+
 object CalculationParser extends StrictLogging {
+
+  /** An exception that indicates failure during parsing.
+    *
+    * @param message Incoming message to parse
+    * @param calculationParser
+    * @param msg
+    * @param what
+    */
   class CalculationParserException(
                                     message: CalculationParserRequest,
                                     calculationParser: CalculationParser,
@@ -27,6 +36,9 @@ object CalculationParser extends StrictLogging {
     what
   )
 }
+/** This class implements methods to run the uncompress the archive (if required) and to run parser.
+  *
+  */
 
 class CalculationParser (
                         val ucRoot: String,
@@ -39,7 +51,8 @@ class CalculationParser (
   var lastUncompressRoot: Option[Path] = None
   val cachedParsers = mutable.Map[String, OptimizedParser]()
 
-  /** Extract all the files from the current level on
+  /** Hierarchically extract all the files from the current level on.
+    *
     */
   def uncompress(inMsg: CalculationParserRequest, uncompressRoot:Path):Option[Path] = {
     if ((!lastArchivePath.isEmpty || lastUncompressRoot.isDefined || !alreadyUncompressed.isEmpty) && (inMsg.treeFilePath != lastArchivePath || lastUncompressRoot != Some(uncompressRoot))) {
@@ -95,6 +108,10 @@ class CalculationParser (
     }
   }
 
+  /** Main function that handles the incoming request to parse a file. Check if the parser, file to parse exists and whether to overwrite if parsedFileOutputPath exists.
+    * Finally uncompress and call the parser and check the parser result.
+    *
+    */
   def handleParseRequest(inMsg: CalculationParserRequest): CalculationParserResult = {
     var didExist = false
     var created = true
@@ -193,7 +210,7 @@ class CalculationParser (
     )
   }
 
-  /** Cleans up the calculation parser
+  /** Cleans up the after successful completion of calculation parser
     */
   def cleanup(): Unit = {
     for ((_, optParser) <- cachedParsers)

core/src/main/scala/eu/nomad_lab/parsing_queue/TreeParser.scala

@@ -17,6 +17,13 @@ import scala.collection.mutable
 
 
 object TreeParser{
+
+  /** An exception that indicates failure during finding a suitable parser.
+    *
+    * @param message
+    * @param msg
+    * @param what
+    */
   class TreeParserException(
                             message: TreeParserRequest,
                             msg: String,
@@ -33,9 +40,12 @@ class TreeParser(
                   val parserCollection: ParserCollection
                 ) extends StrictLogging {
 
-  /** Find the parsable files and parsers. Return the list of messages
+  /** Find the parsable files and parsers.
     *
-    * */
+    * @param incomingMessage
+    * @return list of messages containing the parsable files and the corresponding parsers.
+    */
+
   def findParser(incomingMessage : TreeParserRequest ) ={
     //Read file and get the corresponding parsers
     var msgList: scala.collection.mutable.MutableList[CalculationParserRequest] = mutable.MutableList()
@@ -134,6 +144,12 @@ class TreeParser(
     }
   }
 
+  /** Scan a tar archive and if possible, find the most appropriate parser for each file in the tar archive
+    *
+    * @param filesToUncompress
+    * @param ais
+    * @return
+    */
   @tailrec final def scanArchivedInputStream(filesToUncompress:Map[String, String], ais:ArchiveInputStream):Map[String, String] = {
     var filesToUC =  filesToUncompress
     Option(ais.getNextEntry) match {