Added additional documentation for Rust Docs. Returns either a graph or a file with triples

Author: bharath181

airplane.json

@@ -1,3 +1,17 @@
+//! # JSON2RDF Converter Library
+//!
+//! This library provides functionality for converting JSON data into RDF format.
+//! It uses `serde_json` for JSON parsing and `oxrdf` to build and manage RDF graphs.
+//!
+//! ## Overview
+//! - Converts JSON data structures into RDF triples, generating a graph representation.
+//! - Supports blank nodes for nested structures and maps JSON properties to RDF predicates.
+//!
+//! ## Features
+//! - Handles JSON Objects, Arrays, Booleans, Numbers, and Strings as RDF triples.
+//! - Allows specifying a custom RDF namespace for generated predicates and objects.
+//! - Outputs the RDF data to a specified file or prints it to the console.
+
 use oxrdf::vocab::xsd;
 use oxrdf::{BlankNode, Graph, Literal, NamedNodeRef, TripleRef};
 
@@ -6,7 +20,34 @@ use std::collections::VecDeque;
 use std::fs::File;
 use std::io::{BufReader, Write};
 
-pub fn json_to_rdf(file_path: &String, namespace: &Option<String>, output_file: &Option<String>) {
+pub enum GraphOrMessage {
+    Graph(Graph),
+    Message(String),
+}
+
+/// Converts JSON data to RDF format.
+///
+/// This function reads JSON data from the specified file, processes it into RDF triples,
+/// and outputs the RDF graph. Users can specify a namespace to use for RDF predicates and
+/// an output file for saving the generated RDF data.
+///
+/// # Arguments
+/// - `file_path`: Path to the JSON file.
+/// - `namespace`: Optional custom namespace for RDF predicates.
+/// - `output_file`: Optional output file path for writing RDF data.
+///
+/// # Example
+/// ```rust
+/// use json2rdf::json_to_rdf;
+///
+/// json_to_rdf(&"test/airplane.json".to_string(), &Some("http://example.com/ns#".to_string()), &Some("output.nt".to_string()));
+/// ```
+
+pub fn json_to_rdf(
+    file_path: &String,
+    namespace: &Option<String>,
+    output_file: &Option<String>,
+) -> Result<GraphOrMessage, String> {
     let rdf_namespace: String = if namespace.is_some() {
         namespace.clone().unwrap()
     } else {
@@ -67,13 +108,44 @@ pub fn json_to_rdf(file_path: &String, namespace: &Option<String>, output_file:
         }
     }
 
-    let mut buffer: Vec<u8> = Vec::new();
-    writeln!(buffer, "{}", graph.to_string()).unwrap();
-
-    let file = File::create("foo.txt");
-    writeln!(file.unwrap(), "{}", String::from_utf8_lossy(&buffer)).unwrap();
+    if let Some(output_path) = output_file {
+        let mut file = File::create(output_path).expect("Error creating file");
+        writeln!(file, "{}", graph).expect("Error writing to file");
+        Ok(GraphOrMessage::Message(format!(
+            "RDF created at: {}",
+            output_path
+        )))
+    } else {
+        Ok(GraphOrMessage::Graph(graph))
+    }
 }
 
+/// This function handles different JSON data types, converting each into RDF triples:
+/// - JSON Objects create new blank nodes and recursively process nested values.
+/// - JSON Arrays iterate over each element and process it as an individual value.
+/// - JSON Booleans, Numbers, and Strings are converted to RDF literals.
+///
+/// # Recursion for Nested Structures
+/// Recursion is used to handle deeply nested JSON structures, which may contain multiple
+/// levels of objects or arrays. This recursive approach allows the function to "dive" into
+/// each nested layer of a JSON structure, creating blank nodes for sub-objects and handling
+/// them as new subjects within the RDF graph. As a result, each level of JSON data is
+/// systematically transformed into RDF triples, regardless of complexity or depth.
+///
+/// # Arguments
+/// - `subject_stack`: Stack of blank nodes representing subjects. Each nested level pushes a new subject to the stack.
+/// - `property`: RDF predicate (property) associated with the JSON value.
+/// - `value`: JSON value to process.
+/// - `graph`: RDF graph where triples are added.
+/// - `namespace`: Namespace for generating predicate URIs.
+///
+/// # JSON Type to RDF Conversion
+/// - **Object**: Creates a blank node and recursively processes key-value pairs.
+/// - **Array**: Iterates over elements and processes each as a separate value.
+/// - **String**: Converts to `xsd:string` literal.
+/// - **Boolean**: Converts to `xsd:boolean` literal.
+/// - **Number**: Converts to `xsd:int` or `xsd:float` literal based on value type.
+
 fn process_value(
     subject_stack: &mut VecDeque<BlankNode>,
     property: &Option<String>,

src/lib.rs

@@ -1,42 +1,91 @@
+//! # JSON2RDF Converter
+//!
+//! This is a Rust-based tool that converts JSON data into RDF format. It uses the `serde_json` crate
+//! for JSON parsing and the `oxrdf` crate to construct RDF graphs.
+//!
+//! ## Features
+//! - Parses JSON input and converts it to RDF triples
+//! - Supports specifying a custom namespace for generated RDF nodes
+//! - Outputs RDF data to a specified file
+//!
+//! ## Usage
+//! Run the JSON2RDF converter from the command line. For detailed usage information, run:
+//! ```
+//! json2rdf --help
+//! ```
+//!
+//! ## Example
+//! To convert a JSON file to RDF format with a specified namespace and output file:
+//! ```
+//! json2rdf convert --namespace http://example.com/ns# --json-files data.json --output-file output.nt
+//! ```
+//! This will take `data.json`, apply the specified namespace, and save the RDF output in `output.nt`.
 use clap::{Parser, Subcommand};
 mod lib;
-/// JSON2RDF Converter
-/// This tool converts JSON data into RDF format.
+
+/// Command-line interface for JSON2RDF Converter
+///
+/// This struct defines the command-line interface (CLI) for interacting with the JSON2RDF converter.
 #[derive(Parser)]
-#[command(version, about, long_about = None)]
+#[command(version, about = "Converts JSON data into RDF format.")]
 struct Cli {
+    /// CLI command selection
     #[command(subcommand)]
     command: Option<Commands>,
 }
 
+/// Supported Commands
+///
+/// Contains the available commands for the JSON2RDF converter.
 #[derive(Subcommand)]
 enum Commands {
-    /// The JSON2RDF CLI
+    /// Convert JSON to RDF format.
+    ///
+    /// The `convert` command parses a JSON file, converts it to RDF triples using `serde_json` for parsing
+    /// and `oxrdf` to construct the graph, and saves the output.
     Convert {
-        /// namespace to be used for graph generation
+        /// Namespace for RDF graph generation.
+        ///
+        /// A custom namespace to prefix RDF resources created from JSON keys and values.
         #[arg(short, long)]
         namespace: Option<String>,
-        /// path to JSON file(s)
+
+        /// Path to input JSON file(s).
+        ///
+        /// Provide the path to one or more JSON files that will be parsed and converted.
         #[arg(short, long)]
         json_files: String,
-        /// write triples from oxrdf graph to a file
+
+        /// Path to output file.
+        ///
+        /// Optional: Specify the path to save the generated RDF data.
         #[arg(short, long)]
         output_file: Option<String>,
     },
 }
+
 fn main() {
     let cli = Cli::parse();
 
+    // Match command and execute corresponding functionality
     match &cli.command {
         Some(Commands::Convert {
             namespace,
             json_files,
             output_file,
         }) => {
-            if Some(output_file).is_some() {
-                lib::json_to_rdf(json_files, namespace, output_file);
-            } else {
-                lib::json_to_rdf(json_files, namespace, &None);
+            match lib::json_to_rdf(json_files, namespace, output_file) {
+                Ok(res) => match res {
+                    lib::GraphOrMessage::Graph(graph) => {
+                        // Handle the case where the function returns a Graph
+                        println!("Graph created with {} triples", graph.len());
+                    }
+                    lib::GraphOrMessage::Message(message) => {
+                        // Handle the case where the function returns a success message
+                        println!("{}", message);
+                    }
+                },
+                Err(e) => eprintln!("Error writing: {}", e),
             }
         }
         None => {}

src/main.rs

@@ -0,0 +1 @@
+