royxgen docs use markdown 🚀 ✨

More examples of rdf_add() argument useage

DESCRIPTION

@@ -29,6 +29,7 @@ Imports: redland,
     methods,
     utils
 RoxygenNote: 6.0.1
+Roxygen: list(markdown = TRUE)
 Suggests: magrittr,
     covr,
     testthat,

NEWS.md

@@ -1,27 +1,39 @@
 # rdflib 0.1.0
 
+## New Features
+
 * add `c()` method to concatenate `rdf` objects
+* `rdf()` supports BDB backend for disk-based storage for large triplestores [#6](https://github.com/cboettig/rdflib/issues/6)
+
+## Minor Improvements
+
+* Numerous improvements to documentation, see 
+  [#9](https://github.com/cboettig/rdflib/issues/9) and 
+  [#10](https://github.com/cboettig/rdflib/issues/10) 
+
+## Bug Fixes 
+
 * `rdf_query` now coerces data into appropriate type 
    if it recognizes the data URI and can match that 
    to an R type (a few XMLSchema types are recognized,
    otherwise still defaults to character string)
-* All methods free memory from any temporary objects they initialize
+* Memory management: All methods free memory from any 
+  temporary objects they initialize, tests free memory.
   (e.g. parsers, serializers, query, statement)
-* rdf includes explicit pointer to storage object
-* rdf constructor supports BDB backend for disk-based triplestore [#6](https://github.com/cboettig/rdflib/issues/6)
-* tests free rdf objects
-* extend unit tests for some of new functionality
-* Add `rdf_free` to free rdf (ideally would be done by GC in redland...)
+* extend unit tests to cover new features
+* `turtle` parser/serializer fixed
 
-# rdflib 0.0.3 (2018-01-02)
+## Deprecated
 
-## New Features
+* `trig` support removed (was never working in redland)
 
-* add paper.md
-* add package level documentation
+
+# rdflib 0.0.3 (2018-01-02)
 
 ## Bug Fixes
 
+* add paper.md
+* add package level documentation
 * set base uri when serializing json-ld to rdf ([#5](https://github.com/cboettig/rdflib/issues/5))
 
 

R/rdf.R

@@ -290,14 +290,28 @@ rdf_query <- function(rdf, query, ...){
 #' @param subject character string containing the subject
 #' @param predicate character string containing the predicate
 #' @param object character string containing the object
-#' @param subjectType the Node type of the subject, i.e. "blank", "uri"
-#' @param objectType the Node type of the object, i.e. "blank", "uri", "literal"
+#' @param subjectType the Node type of the subject, i.e. "uri", "blank"
+#' @param objectType the Node type of the object, i.e. "literal", "uri", "blank"
 #' @param datatype_uri the datatype URI to associate with a object literal value
 #'
-#' @return the updated RDF graph (rdf object).
-#' @details Since the rdf object simply contains external pointers
+#' @return Silently returns the updated RDF graph (rdf object).
+#' Since the rdf object simply contains external pointers
 #' to the model object in C code, note that the input object is modified
-#' directly.  
+#' directly, so you need not assign the output of rdf_add() to anything.
+#'
+#' @details 
+#' 
+#' - Predicate should always be a 
+#'   [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier).
+#' - Subject should be either URI or a character string.  If subject string
+#'   does not look like a URI (e.g. a URL or a `prefix:string`), it
+#'   will be typed as a blank node and prefixed with `_:` automatically,
+#'   equivalent to setting `subjectType="blank"`, See examples.
+#' - Object will automatically type URIs as URIs, strings as literals,
+#'   and empty strings as blank nodes. Override by setting `objectType`
+#'   explicitly (e.g. to treat a URL as a literal; see examples)
+#' 
+#' @references <https://en.wikipedia.org/wiki/Uniform_Resource_Identifier>
 #' @importClassesFrom redland Statement
 #' @importMethodsFrom redland addStatement freeStatement
 #' @export
@@ -309,9 +323,32 @@ rdf_query <- function(rdf, query, ...){
 #'     predicate="http://purl.org/dc/elements/1.1/language",
 #'     object="en")
 #'     
-#' ## blank nodes should be declared as such:
-#' rdf_add(rdf, "", "http://schema.org/jobTitle", "Professor", 
-#'         subjectType = "blank")   
+#' ## non-URI string in subject indicates a blank subject
+#' ## (prefixes to "_:b0")
+#' rdf_add(rdf, "b0", "http://schema.org/jobTitle", "Professor") 
+#' 
+#' ## identically a blank subject.  
+#' ## Note rdf is unchanged when we add the same triple twice.
+#' rdf_add(rdf, "b0", "http://schema.org/jobTitle", "Professor", 
+#'         subjectType = "blank") 
+#'         
+#' ## blank node with empty string creates a default blank node id
+#' rdf_add(rdf, "", "http://schema.org/jobTitle", "Professor")   
+#'                     
+#' 
+#' ## Subject and Object both recognized as URI resources:
+#' rdf_add(rdf, 
+#'         "https://orcid.org/0000-0002-1642-628X",
+#'         "http://schema.org/homepage", 
+#'         "http://carlboettiger.info")  
+#'
+#'  ## Force object to be literal, not URI resource        
+#' rdf_add(rdf, 
+#'         "https://orcid.org/0000-0002-1642-628X",
+#'         "http://schema.org/homepage", 
+#'         "http://carlboettiger.info",
+#'         objectType = "literal")  
+#'         
 #'
 rdf_add <- function(rdf, subject, predicate, object, 
                     subjectType = as.character(NA),