Documentation enhancements using Roxygen

2015-08-05 17:56:17 +01:00 · 2015-08-05 17:56:17 +01:00 · ab7fc07ac1
--- a/maml/R/discover.R
+++ b/maml/R/discover.R
@ -1,18 +1,8 @@
-# The discovery code allows the user to retrieve a list of the web services available in
-# their workspace given that they provide the workspace ID and the authorization token
-# (both of which can be found in settings on the AzureML webpage). A user can also get
-# detailed information about a specific web service, retrieve its endpoints, and the
-# details of a specific endpoint.
-# @docType package
-# @name maml
-#NULL



+# API URLs ----------------------------------------------------------------

-#############################################################
-# API URLs
-#############################################################
 wsURL = "https://management-tm.azureml.net/workspaces/%s/webservices"
 wsURLdet = "https://management-tm.azureml.net/workspaces/%s/webservices/%s"
 epURL = "https://management-tm.azureml.net/workspaces/%s/webservices/%s/endpoints"
@ -25,16 +15,21 @@ internalURL = "https://management.azureml-int.net/workspaces/%s/webservices/%s/e
 internalURL = "https://management.azureml-int.net"
 prodURL = "https://management-tm.azureml.net"

-#############################################################
-#' @title Get FrameWork
-#' @description
-#' Framework for making an HTTP request to the URL specified
-#' returns a list of lists, so that the elements can be accessed
-#' via double bracket notation
+
+#  ------------------------------------------------------------------------
+
+#' Get FrameWork.
+#' 
+#' Framework for making an HTTP request to the URL specified returns a list of lists, so that the elements can be accessed via double bracket notation
+#' 
 #' @param tUrl The URL from the published web service
 #' @param authToken The authentication token for the AzureML account being used
+#' 
+#' @family discovery internal functions
+#' 
+#' @keywords Internal
+#' 
 #' @return prints the framework
-#############################################################
 getFramework <- function(tUrl, authToken) {
  # Collectors for API response
  h = RCurl::basicTextGatherer()
@ -67,20 +62,31 @@ getFramework <- function(tUrl, authToken) {



-#############################################################
-#' @title Get Web Services
+#' Get Web Services.
+#' 
+#' Get a list of webservices available to a workspace
+
 #' @export
-#' @description Get a list of webservices available to a workspace
 #'
 #' @param wkID The workspace ID
 #' @param authToken The primary authorization token
-#' @return Returns a list of lists, where each web service is represented
-#' as a nested named list with the following fields:
-#' "Id", "Name", "Description", "CreationTime", "WorkspaceId", "DefaultEndpointName"
+#' 
+#' @family Discovery functions
+#' 
+#' @return Returns a list of lists, where each web service is represented as a nested named list with the following fields:
+#' 
+#' \itemize{
+#'   \item Id
+#'   \item Name
+#'   \item Description
+#'   \item CreationTime
+#'   \item WorkspaceId
+#'   \item DefaultEndpointName
+#' }
+#' 
 # @examples
 # services = getWebServices("c01fb89129aa4ef0a19affa7f95ecbbc", "523709d06661441bbf129d68f84cd6a4")
 # serviceID = services[[1]]["Id"]
-#############################################################
 getWebServices <- function(wkID, authToken, url=prodURL) {
  response = getFramework(sprintf(paste(url,"/workspaces/%s/webservices",sep=""), wkID), authToken)
  if (!is.list(response)) {
@ -91,34 +97,49 @@ getWebServices <- function(wkID, authToken, url=prodURL) {



-#############################################################
-#' @title Get Workspace Details
+#' Get Workspace Details.
+#' 
+#' Get detailed information about a specific webservice
+
 #' @export
-#' @description Get detailed information about a specific webservice
-#'
-#' @param wkID The workspace ID
-#' @param authToken The primary authorization token
+#' 
+#' @family Discovery functions
+#' 
+#' @inheritParams getWebServices
 #' @param wsID The webservice ID
-#' @return Returns a named list representing the web service
-#' with the following fields:
-#' "Id", "Name", "Description", "CreationTime", "WorkspaceId", "DefaultEndpointName"
-# @examples
-# services = getWebServices("abcdefghijklmnopqrstuvwxyz123456", "abcdefghijklmnopqrstuvwxyz123456")
-#############################################################
+#' 
+#' @return Returns a list of lists, where each web service is represented as a nested named list with the following fields:
+#' 
+#' \itemize{
+#'   \item Id
+#'   \item Name
+#'   \item Description
+#'   \item CreationTime
+#'   \item WorkspaceId
+#'   \item DefaultEndpointName
+#' }
+#' @examples
+#' \dontrun{
+#' services = getWebServices("abcdefghijklmnopqrstuvwxyz123456", "abcdefghijklmnopqrstuvwxyz123456")
+#' }
 getWSDetails <- function(wkID, authToken, wsID, url=prodURL) {
  return(getFramework(sprintf(paste(url, "/workspaces/%s/webservices/%s", sep=""), wkID, wsID), authToken))
 }



-#############################################################
-#' @title Get Endpoints
+#' Get Endpoints.
+
+#' Get the endpoints that are part of a web service
+#' 
 #' @export
-#' @description Get the endpoints that are part of a web service
+#' 
+#' @inheritParams getWSDetails
+#' 
+#' @seealso For publishing to AzureML, see \code{\link{publishWebService}}
+#' @family Discovery functions
+#' 
 #'
-#' @param wkID The workspace ID
-#' @param authToken The primary authorization token
-#' @param wsID The webservice ID
 #' @return Returns a list of lists, where each endpoint is represented
 #' as a nested named list with the following fields:
 #' "Name", "Description", "CreationTime", "WorkspaceId", "WebServiceId",
@ -126,7 +147,6 @@ getWSDetails <- function(wkID, authToken, wsID, url=prodURL) {
 #' "MaxConcurrentCalls", "DiagnosticsTraceLevel", "ThrottleLevel"
 # @examples
 # endpoints = getEndpoints("abcdefghijklmnopqrstuvwxyz123456", "abcdefghijklmnopqrstuvwxyz123456", "abcdefghijklmnopqrstuvwxyz123456")
-#############################################################
 getEndpoints <- function(wkID, authToken, wsID, url=prodURL) {
  response <- getFramework(sprintf(paste(url, "/workspaces/%s/webservices/%s/endpoints", sep=""), wkID, wsID), authToken)
  # for convenience because by default the repsonse doesn't include the full API location
@ -138,22 +158,23 @@ getEndpoints <- function(wkID, authToken, wsID, url=prodURL) {



-#############################################################
-#' @title get Endpoint Details
+#' Get Endpoint Details.
+#' 
+#' Get the details on a specific endpoint
+#' 
 #' @export
-#' @description Get the details on a specific endpoint
+#' 
+#' @family Discovery functions
 #'
-#' @param wkID The workspace ID
-#' @param authToken The primary authorization token
-#' @param wsID The webservice ID
+#' @inheritParams getWSDetails
 #' @param epName The endpoint name
+#' 
 #' @return Returns a named list representing the endpoint with the following fields:
 #' "Name", "Description", "CreationTime", "WorkspaceId", "WebServiceId",
 #' "HelpLocation", "PrimaryKey", "SecondaryKey", "ApiLocation", "Version",
 #' "MaxConcurrentCalls", "DiagnosticsTraceLevel", "ThrottleLevel"
 # @examples
 # defaultEP = getEPDetails("abcdefghijklmnopqrstuvwxyz123456", "abcdefghijklmnopqrstuvwxyz123456", "abcdefghijklmnopqrstuvwxyz123456", "default")
-#############################################################
 getEPDetails <- function(wkID, authToken, wsID, epName, url=prodURL) {
  sprintf(paste(url, "/workspaces/%s/webservices/%s/endpoints/%s", sep=""), wkID, wsID, epName)
  endpoint <- getFramework(sprintf(paste(url, "/workspaces/%s/webservices/%s/endpoints/%s", sep=""), wkID, wsID, epName), authToken)
--- a/maml/R/maml-package.R
+++ b/maml/R/maml-package.R
@ -0,0 +1,23 @@
+#' Allows you to discover, publish and consume Azure ML web services
+#' 
+#' The discovery code allows the user to retrieve a list of the web services available in their workspace given that they provide the workspace ID and the authorization token (both of which can be found in settings on the AzureML webpage). A user can also get detailed information about a specific web service, retrieve its endpoints, and the details of a specific endpoint.
+#' 
+#' 1. Discovery
+#' 
+#' \itemize{
+#'   \item Get endpoints: \code{\link{getEndpoints}}
+#' }
+#' 
+#' 2. Publish
+#' 
+#' blah
+#' 
+#' 3. Consume
+#' 
+#' blah
+#' 
+#' @name maml-package
+#' @aliases maml
+#' @docType package
+#' @keywords package
+?NULL
--- a/maml/man/getDetailsFromUrl.Rd
+++ b/maml/man/getDetailsFromUrl.Rd
@ -0,0 +1,16 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/consume.R
+\name{getDetailsFromUrl}
+\alias{getDetailsFromUrl}
+\title{This function is a helper that takes in the help URL, and parses the endpoint and workspace from it
+This function also documents the assumption that the help URL will end in the format "endpoints/"endpointId/(other keywords)
+This function also documents the assumption that the help URL will}
+\usage{
+getDetailsFromUrl(helpURL)
+}
+\description{
+This function is a helper that takes in the help URL, and parses the endpoint and workspace from it
+This function also documents the assumption that the help URL will end in the format "endpoints/"endpointId/(other keywords)
+This function also documents the assumption that the help URL will
+}
+
--- a/maml/man/getEPDetails.Rd
+++ b/maml/man/getEPDetails.Rd
@ -2,7 +2,7 @@
 % Please edit documentation in R/discover.R
 \name{getEPDetails}
 \alias{getEPDetails}
-\title{get Endpoint Details}
+\title{Get Endpoint Details.}
 \usage{
 getEPDetails(wkID, authToken, wsID, epName, url = prodURL)
 }
@ -24,4 +24,8 @@ Returns a named list representing the endpoint with the following fields:
 \description{
 Get the details on a specific endpoint
 }
+\seealso{
+Other Discovery functions: \code{\link{getEndpoints}};
+  \code{\link{getWSDetails}}; \code{\link{getWebServices}}
+}

--- a/maml/man/getEndpoints.Rd
+++ b/maml/man/getEndpoints.Rd
@ -2,7 +2,8 @@
 % Please edit documentation in R/discover.R
 \name{getEndpoints}
 \alias{getEndpoints}
-\title{Get Endpoints}
+\title{Get Endpoints.
+Get the endpoints that are part of a web service}
 \usage{
 getEndpoints(wkID, authToken, wsID, url = prodURL)
 }
@ -21,6 +22,13 @@ as a nested named list with the following fields:
 "MaxConcurrentCalls", "DiagnosticsTraceLevel", "ThrottleLevel"
 }
 \description{
+Get Endpoints.
 Get the endpoints that are part of a web service
 }
+\seealso{
+For publishing to AzureML, see \code{\link{publishWebService}}
+
+Other Discovery functions: \code{\link{getEPDetails}};
+  \code{\link{getWSDetails}}; \code{\link{getWebServices}}
+}

--- a/maml/man/getFramework.Rd
+++ b/maml/man/getFramework.Rd
@ -2,7 +2,7 @@
 % Please edit documentation in R/discover.R
 \name{getFramework}
 \alias{getFramework}
-\title{Get FrameWork}
+\title{Get FrameWork.}
 \usage{
 getFramework(tUrl, authToken)
 }
@ -15,8 +15,7 @@ getFramework(tUrl, authToken)
 prints the framework
 }
 \description{
-Framework for making an HTTP request to the URL specified
-returns a list of lists, so that the elements can be accessed
-via double bracket notation
+Framework for making an HTTP request to the URL specified returns a list of lists, so that the elements can be accessed via double bracket notation
 }
+\keyword{Internal}

--- a/maml/man/getFunctionString.Rd
+++ b/maml/man/getFunctionString.Rd
@ -10,7 +10,7 @@ getFunctionString(x)
 \item{x}{Name of the function to convert to a string}
 }
 \value{
-function in string format
+source code of the function as a string
 }
 \description{
 This is a helper function that will convert a function's source code to a string
--- a/maml/man/getWSDetails.Rd
+++ b/maml/man/getWSDetails.Rd
@ -2,7 +2,7 @@
 % Please edit documentation in R/discover.R
 \name{getWSDetails}
 \alias{getWSDetails}
-\title{Get Workspace Details}
+\title{Get Workspace Details.}
 \usage{
 getWSDetails(wkID, authToken, wsID, url = prodURL)
 }
@ -14,11 +14,27 @@ getWSDetails(wkID, authToken, wsID, url = prodURL)
 \item{wsID}{The webservice ID}
 }
 \value{
-Returns a named list representing the web service
-with the following fields:
-"Id", "Name", "Description", "CreationTime", "WorkspaceId", "DefaultEndpointName"
+Returns a list of lists, where each web service is represented as a nested named list with the following fields:
+
+\itemize{
+  \item Id
+  \item Name
+  \item Description
+  \item CreationTime
+  \item WorkspaceId
+  \item DefaultEndpointName
+}
 }
 \description{
 Get detailed information about a specific webservice
 }
+\examples{
+\dontrun{
+services = getWebServices("abcdefghijklmnopqrstuvwxyz123456", "abcdefghijklmnopqrstuvwxyz123456")
+}
+}
+\seealso{
+Other Discovery functions: \code{\link{getEPDetails}};
+  \code{\link{getEndpoints}}; \code{\link{getWebServices}}
+}

--- a/maml/man/getWebServices.Rd
+++ b/maml/man/getWebServices.Rd
@ -2,7 +2,7 @@
 % Please edit documentation in R/discover.R
 \name{getWebServices}
 \alias{getWebServices}
-\title{Get Web Services}
+\title{Get Web Services.}
 \usage{
 getWebServices(wkID, authToken, url = prodURL)
 }
@ -12,11 +12,22 @@ getWebServices(wkID, authToken, url = prodURL)
 \item{authToken}{The primary authorization token}
 }
 \value{
-Returns a list of lists, where each web service is represented
-as a nested named list with the following fields:
-"Id", "Name", "Description", "CreationTime", "WorkspaceId", "DefaultEndpointName"
+Returns a list of lists, where each web service is represented as a nested named list with the following fields:
+
+\itemize{
+  \item Id
+  \item Name
+  \item Description
+  \item CreationTime
+  \item WorkspaceId
+  \item DefaultEndpointName
+}
 }
 \description{
 Get a list of webservices available to a workspace
 }
+\seealso{
+Other Discovery functions: \code{\link{getEPDetails}};
+  \code{\link{getEndpoints}}; \code{\link{getWSDetails}}
+}

--- a/maml/man/maml-package.Rd
+++ b/maml/man/maml-package.Rd
@ -0,0 +1,27 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/maml-package.R
+\docType{package}
+\name{maml-package}
+\alias{maml}
+\alias{maml-package}
+\title{Allows you to discover, publish and consume Azure ML web services}
+\description{
+The discovery code allows the user to retrieve a list of the web services available in their workspace given that they provide the workspace ID and the authorization token (both of which can be found in settings on the AzureML webpage). A user can also get detailed information about a specific web service, retrieve its endpoints, and the details of a specific endpoint.
+}
+\details{
+1. Discovery
+
+\itemize{
+  \item Get endpoints: \code{\link{getEndpoints}}
+}
+
+2. Publish
+
+blah
+
+3. Consume
+
+blah
+}
+\keyword{package}
+
--- a/maml/man/packDependencies.Rd
+++ b/maml/man/packDependencies.Rd
@ -7,10 +7,10 @@
 packDependencies(functionName)
 }
 \arguments{
-\item{closure}{functionName - function to package dependencies from}
+\item{functionName}{function to package dependencies from}
 }
 \value{
-encoded zip - will return false if nothing was zipped
+list containing the guid for the rdta file and the encoded zip
 }
 \description{
 This is a helper function to extract object and package dependencies
--- a/maml/man/publishPreprocess.Rd
+++ b/maml/man/publishPreprocess.Rd
@ -0,0 +1,18 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/publish.R
+\name{publishPreprocess}
+\alias{publishPreprocess}
+\title{HELPER FUNCTION: Convert Format}
+\usage{
+publishPreprocess(argList)
+}
+\arguments{
+\item{list}{argList - List of expected input parameters}
+}
+\value{
+Converted inputSchema to the proper format
+}
+\description{
+This is a helper function to convert expected schema to API-expecting format
+}
+
--- a/maml/tests/testthat/.gitignore
+++ b/maml/tests/testthat/.gitignore
@ -0,0 +1 @@
+0-config.R
--- a/maml/tests/testthat/testDiscover.R
+++ b/maml/tests/testthat/testDiscover.R
@ -1,44 +1,44 @@
-#test_that("Can discover endpoints starting from workspace ID", {
-#  skip_on_cran() # requires internet connection
+source("maml/tests/testthat/0-config.R")
+if(interactive()) library(testthat)

-#  testID = ""
-#  testAuth = ""
-#  webservices <- getWebServices(testID, testAuth)
-#  Sys.sleep(1)
-#  testWS <- getWSDetails(testID, testAuth, webservices[[1]]$Id)
-#  Sys.sleep(1)
-#  endpoints <- getEndpoints(testID, testAuth, testWS$Id)
-#  Sys.sleep(1)
-#  testEP <- getEPDetails(testID, testAuth, testWS$Id, endpoints[[1]]$Name)
+test_that("Can discover endpoints starting from workspace ID", {
+ skip_on_cran() # requires internet connection

-#  expect_equal(length(webservices), 1)
-#  expect_equal(length(testWS), 7)
-#  expect_equal(length(endpoints),1)
-#  expect_equal(length(testEP), 14)
-#  expect_equal(webservices[[1]]$Id, testWS$Id)
-#  expect_equal(testWS$Id, endpoints[[1]]$WorkspaceId)
-#  expect_equal(endpoints[[1]]$WebServiceId, testEP$WebServiceId)
-#  expect_equal(endpoints[[1]]$Name, testEP$Name)
-#})
+ 
+ webservices <- getWebServices(testID, testAuth)
+ Sys.sleep(1)
+ testWS <- getWSDetails(testID, testAuth, webservices[[1]]$Id)
+ Sys.sleep(1)
+ endpoints <- getEndpoints(testID, testAuth, testWS$Id)
+ Sys.sleep(1)
+ testEP <- getEPDetails(testID, testAuth, testWS$Id, endpoints[[1]]$Name)
+
+ expect_equal(length(webservices), 1)
+ expect_equal(length(testWS), 7)
+ expect_equal(length(endpoints),1)
+ expect_equal(length(testEP), 14)
+ expect_equal(webservices[[1]]$Id, testWS$Id)
+ expect_equal(testWS$Id, endpoints[[1]]$WorkspaceId)
+ expect_equal(endpoints[[1]]$WebServiceId, testEP$WebServiceId)
+ expect_equal(endpoints[[1]]$Name, testEP$Name)
+})


-#test_that("API location is returned and able to be used immediately", {
-#  skip_on_cran() # requires internet connection
+test_that("API location is returned and able to be used immediately", {
+ skip_on_cran() # requires internet connection

-#  testID = ""
-#  testAuth = ""
-#  webservices <- getWebServices(testID, testAuth)
-#  Sys.sleep(1)
-#  endpoints <- getEndpoints(testID, testAuth, webservices[[1]]$Id)
-#  Sys.sleep(1)
-#  response <- consumeDataTable(endpoints[[1]]$PrimaryKey, endpoints[[1]]$ApiLocation, list("FlowerId", "SepalLength", "SepalWidth", "PetalLength", "PetalWidth", "Species"), list(1, 6.5, 5.5, 3.5, 4.5, 0))
+ webservices <- getWebServices(testID, testAuth)
+ Sys.sleep(1)
+ endpoints <- getEndpoints(testID, testAuth, webservices[[1]]$Id)
+ Sys.sleep(1)
+ response <- consumeDataTable(endpoints[[1]]$PrimaryKey, endpoints[[1]]$ApiLocation, list("FlowerId", "SepalLength", "SepalWidth", "PetalLength", "PetalWidth", "Species"), list(1, 6.5, 5.5, 3.5, 4.5, 0))

-#  expect_true(is.data.frame(response))
-#  expect_equal(as.numeric(response[1,8]), 1)
-#})
+ expect_true(is.data.frame(response))
+ expect_equal(as.numeric(response[1,8]), 1)
+})


-#test_that("Discovery function handles error correctly", {
-#  skip_on_cran()
-#  expect_error(getWebServices("foo", testAuth), "InvalidWorkspaceIdInvalid workspace ID provided. Verify the workspace ID is correct and try again.")
-#})
+test_that("Discovery function handles error correctly", {
+ skip_on_cran()
+ expect_error(getWebServices("foo", testAuth), "InvalidWorkspaceIdInvalid workspace ID provided. Verify the workspace ID is correct and try again.")
+})