diff --git a/src/core.jl b/src/core.jl
index cb8abd17..3c6659fa 100644
--- a/src/core.jl
+++ b/src/core.jl
@@ -44,15 +44,14 @@ julia> add_vertices!(g, 2)
 """
 add_vertices!(g::AbstractGraph, n::Integer) = sum([add_vertex!(g) for i in 1:n])
 
-# TODO the behaviour of indegree (and as well outdegree and degree) is very
-# badly documented for the case indegree(g, vs) where vs is not a single vertex
-# but rather a collection of vertices
-
 """
     indegree(g[, v])
 
-Return a vector corresponding to the number of edges which end at each vertex in
-graph `g`. If `v` is specified, only return degrees for vertices in `v`.
+Return a vector containing the indegrees of every vertex of the graph `g`, where
+the indegree of a vertex is defined as the number of edges which end at that 
+vertex. If `v` is specified and is a single vertex, only return the indegree of
+`v`. If `v` is specified and is a vector of vertices, only return the indegrees
+of the vertices in `v`.
 
 # Examples
 ```jldoctest
@@ -69,6 +68,14 @@ julia> indegree(g)
  1
  0
  1
+
+julia> indegree(g,[2,3])
+2-element Vector{Int64}:
+ 0
+ 1
+
+julia> indegree(g,2)
+0
 ```
 """
 indegree(g::AbstractGraph, v::Integer) = length(inneighbors(g, v))
@@ -77,8 +84,11 @@ indegree(g::AbstractGraph, vs=vertices(g)) = [indegree(g, x) for x in vs]
 """
     outdegree(g[, v])
 
-Return a vector corresponding to the number of edges which start at each vertex in
-graph `g`. If `v` is specified, only return degrees for vertices in `v`.
+Return a vector containing the outdegrees of every vertex of the graph `g`, where
+the outdegree of a vertex is defined as the number of edges which start at that 
+vertex. If `v` is specified and is a single vertex, only return the outdegree of
+`v`. If `v` is specified and is a vector of vertices, only return the outdegrees
+of the vertices in `v`.
 
 # Examples
 ```jldoctest
@@ -95,6 +105,14 @@ julia> outdegree(g)
  0
  1
  1
+
+julia> outdegree(g,[1,2])
+2-element Vector{Int64}:
+ 0
+ 1
+
+julia> outdegree(g,2)
+1
 ```
 """
 outdegree(g::AbstractGraph, v::Integer) = length(outneighbors(g, v))
@@ -103,10 +121,12 @@ outdegree(g::AbstractGraph, vs=vertices(g)) = [outdegree(g, x) for x in vs]
 """
     degree(g[, v])
 
-Return a vector corresponding to the number of edges which start or end at each
-vertex in graph `g`. If `v` is specified, only return degrees for vertices in `v`.
-For directed graphs, this value equals the incoming plus outgoing edges.
-For undirected graphs, it equals the connected edges.
+Return a vector containing the degrees of every vertex of the graph `g`, where
+the degree of a vertex is defined as the number of edges which start or end at
+that vertex. For directed graphs, the degree of a vertex is equal to the sum of
+its indegree and outdegree. If `v` is specified and is a single vertex, only 
+return the degree of `v`. If `v` is specified and is a vector of vertices, only
+return the degrees of the vertices in `v`.
 
 # Examples
 ```jldoctest
@@ -123,6 +143,14 @@ julia> degree(g)
  1
  1
  2
+
+julia> degree(g,[1,3])
+2-element Vector{Int64}:
+ 1
+ 2
+
+julia> degree(g,3)
+2
 ```
 """
 function degree end