How to combine with existing APIs

Because of the backwards support, we will not change the namespace of the existing APIs. There are currently three approaches we can take:

• Add a new Class/Object called "Symbol.api._" with full implementation there
• Create a new Class and change the name space for all of the functions (e.g Activation -> NewActivation) and let Symbol/NDArray extends that
• Create a new Class and override the Same functions with different implementations.

After some research and discussion with Scala Interest Group, we found that the third approach will be nearly impossible to achieve. Here is a minimum reproduction of the problem of what we will be facing:

package scalaMig

object Test extends TestBase {
  
  def Activation(name : String = null)() = {
    println("Hello")
  }

  def main(args : Array[String]) = {
    Activation("hi")
  }


}

class TestBase {
  def Activation(data : Option[Int] = None) : Unit = {
    println("Hello World")
  }
}

This will cause the 

"Error:(3, 8) in object Test, multiple overloaded alternatives of method Activation define default arguments.
The members with defaults are defined in object Test in package scalaMig and class TestBase in package scalaMig.
object Test extends TestBase {"

This is a limitation of Scala language as it does not have a good support for overriding default args. If we need to solve this problem, we may need to create a bunch of override functions with different configuration. 

How to add API documentation

The current solution for this is to create a signature file contains abstract classes such as SymbolBase and NDArrayBase. These files will include the signature of the function as well as Function definition docs. These file can be used to generate the API site. The integration of the API is as shown as follows:

class NDArray extends NDArrayBase {
  val api : NDArrayAPIBase = NDArrayAPI
}


class NDArrayAPI extends NDArrayAPIBase {
}

As shown above, there will be in total 4 signature files generated through this process. We decided not to upload them as the size of them are massive. As an alternative, we create a hash check scheme to avoid operator changes. I used md5 hash in here:

  def MD5Generator(input : String) : String = {
    val md = MessageDigest.getInstance("MD5")
    md.update(input.getBytes("UTF-8"))
    val digest = md.digest()
    org.apache.commons.codec.binary.Base64.encodeBase64URLSafeString(digest)
  }

It basically take the Generated string into hash and store in this file. It should be the same across the different platform. The reason to do is is to avoid operator changes in Symbol and NDArray. One example, if one contributor changed the operators in NDArray and Symbol, he/she should comment the require line explained before in Scala package and update this file and also tag Scala Contributors to let them know there is a change in operator so we can determine if this will influence the user experience on Scala.