chapter_preliminaries/lookup-api.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "origin_pos": 0
   },
   "source": [
    "# Documentation\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "origin_pos": 1,
    "tab": [
     "mxnet"
    ]
   },
   "source": [
    "Due to constraints on the length of this book, we cannot possibly introduce every single DJL function and class (and you probably would not want us to). The API documentation and additional tutorials and examples provide plenty of documentation beyond the book. In this section we provide you with some guidance to exploring the DJL API."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "origin_pos": 4
   },
   "source": [
    "## Finding All the Functions and Classes in a Module\n",
    "\n",
    "In order to know which functions and classes can be called, we can go to the\n",
    "javadocs for DJL which can be seen here: https://javadoc.io/doc/ai.djl/api/latest/index.html\n",
    "\n",
    "There we can search for the class that we are interested in exploring. For instance,\n",
    "we can go to the `All Classes` box on the left and search for `NDManager`. In this class\n",
    "you will see all the functions that can be called and any information or documentation\n",
    "regarding them.\n",
    "\n",
    "https://javadoc.io/doc/ai.djl/api/latest/ai/djl/ndarray/NDManager.html\n",
    "\n",
    "To explore an example, if we were interested in functions that handled generating\n",
    "`NDArray`s with random numbers, we could search for the functions that start with `random` or \n",
    "that contain `random` in their description. By doing this, we can see that there are\n",
    "a few functions that actually do what we want. To mention a few:\n",
    "- randomInteger(long low, long high, Shape shape, DataType dataType)\n",
    "- randomMultinomial(int n, NDArray pValues)\n",
    "- randomMultinomial(int n, NDArray pValues, Shape shape)\n",
    "- randomNormal(float loc, float scale, Shape shape, DataType dataType)\n",
    "- randomUniform(float low, float high, Shape shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "origin_pos": 8
   },
   "source": [
    "## Finding the Usage of Specific Functions and Classes\n",
    "\n",
    "For more specific instructions on how to use a given function or class, we can click the desired function or go to it directly by scrolling down and searching for it. As an example, let us explore the usage instructions for `NDManager`'s `ones` function which takes a `Shape` as a parameter. \n",
    "\n",
    "https://javadoc.io/static/ai.djl/api/0.23.0/ai/djl/ndarray/NDManager.html#ones(ai.djl.ndarray.types.Shape)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "origin_pos": 12
   },
   "source": [
    "From the documentation, we can see that the `ones` function creates a new `NDArray` with the specified shape and sets all the elements to the value of 1. Whenever possible, you should run a quick test to confirm your interpretation:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%load ../utils/djl-imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "NDManager manager = NDManager.newBaseManager();\n",
    "manager.ones(new Shape(4))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "origin_pos": 16
   },
   "source": [
    "## Summary\n",
    "\n",
    "* The official documentation provides plenty of descriptions and examples that are beyond this book.\n",
    "* We can look up documentation for the usage of an API by accessing the javadoc directly.\n",
    "\n",
    "\n",
    "## Exercises\n",
    "\n",
    "1. Look up the documentation for any function or class in the deep learning framework MXNet. Can you also find the documentation on the official DJL website?"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Java",
   "language": "java",
   "name": "java"
  },
  "language_info": {
   "codemirror_mode": "java",
   "file_extension": ".jshell",
   "mimetype": "text/x-java-source",
   "name": "Java",
   "pygments_lexer": "java",
   "version": "14.0.2+12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}