graph_kernel: add doc

Author: WeiyueSu

pgl/graph_kernel.pyx

@@ -253,10 +253,22 @@ def sample_subset_with_eid(list nids, list eids, long long maxdegree, shuffle=Fa
 
 @cython.boundscheck(False)
 @cython.wraparound(False)
-def skip_gram_gen_pair(vector[long long] walk, long win_size=5):
+def skip_gram_gen_pair(vector[long long] walk_path, long win_size=5):
+    """Return node paris generated by skip-gram algorithm.
+
+    This function will auto remove the pair which src node is the same 
+    as dst node.
+
+    Args:
+        walk_path: List of nodes as a walk path.
+        win_size: the windows size used in skip-gram.
+
+    Return:
+        A tuple of (src node list, dst node list).
+    """
     cdef vector[long long] src
     cdef vector[long long] dst
-    cdef long long l = len(walk)
+    cdef long long l = len(walk_path)
     cdef long long real_win_size, left, right, i
     cdef np.ndarray[np.int64_t, ndim=1] rnd = np.random.randint(1,  win_size+1,
                                     dtype=np.int64, size=l)
@@ -270,15 +282,23 @@ def skip_gram_gen_pair(vector[long long] walk, long win_size=5):
             if right >= l:
                 right = l - 1
             for j in xrange(left, right+1):
-                if walk[i] == walk[j]:
+                if walk_path[i] == walk_path[j]:
                     continue
-                src.push_back(walk[i])
-                dst.push_back(walk[j])
+                src.push_back(walk_path[i])
+                dst.push_back(walk_path[j])
     return src, dst
 
 @cython.boundscheck(False)
 @cython.wraparound(False)
 def alias_sample_build_table(np.ndarray[np.float64_t, ndim=1] probs):
+    """Return the alias table and event table for alias sampling.
+
+    Args:
+        porobs: A list of float numbers as the probability.
+
+    Return:
+        A tuple of (alias table, event table).
+    """
     cdef long long l = len(probs)
     cdef np.ndarray[np.float64_t, ndim=1] alias = probs * l
     cdef np.ndarray[np.int64_t, ndim=1] events = np.zeros(l, dtype=np.int64)