Updated the config options and modified the unit test accordingly. Updated documentation to include parameters for the fuctions.

Author: chrisdbeard

README.md

@@ -72,6 +72,8 @@ You can update these by searching for “Rust Doc String Generator” or "rustdo
 "rustdocstring.inludeSafetyDetails": false
 ```
 
+---
+
 ## How It Works
 
 RustDocString uses a signature parser (`utils.js`) to scan for the next Rust item and normalize its declaration. Then, depending on the item type:

src/docgen.js

@@ -1,20 +1,24 @@
 const { generateFunctionDoc } = require('./gen_fn_doc.js');
 const { generateStructDoc } = require('./gen_struct_doc.js');
 const { generateEnumDoc } = require('./gen_enum_doc.js');
-const vscode = require('vscode');
 
 /**
  * Dispatcher for generating Rust doc comments based on the type of code item.
  * Supports functions, structs, enums, and traits. Delegates to specialized handlers.
  *
  * @param {string} line - The normalized line of Rust code (a signature).
+ * @param {Object} options - Configuration options for doc generation.
+ * @param {boolean} [options.includeExamples=true] - Whether to include the `# Examples` section.
+ * @param {boolean} [options.examplesOnlyForPublicOrExtern=false] - Whether to include examples only for `pub` or `extern` items.
+ * @param {boolean} [options.includeSafetyDetails=false] - Whether to include extended safety guidance in the `# Safety` section.
  * @returns {string|null} - The formatted doc comment, or null if unsupported.
  */
-function generateDocComment(line) {
-    const config = vscode.workspace.getConfiguration('rustdocstring');
-    const includeExamples = config.get('includeExamples', true);
-    const examplesOnlyForPublicOrExtern = config.get('examplesOnlyForPublicOrExtern', false);
-    const includeSafetyDetails = config.get('includeSafetyDetails', false);
+function generateDocComment(line, options) {
+    const {
+        includeExamples = true,
+        examplesOnlyForPublicOrExtern = false,
+        includeSafetyDetails = false
+      } = options;
 
     const itemType = getRustItemType(line);
     if (!itemType) return null;

src/extension.js

@@ -9,9 +9,17 @@ function activate(context) {
             if (!line.trim().endsWith('///')) return;
 
 			const signature = findNextSignatureBlock(document, position.line);
+            const config = vscode.workspace.getConfiguration('rustdocstring');
+            const includeExamples = config.get('includeExamples', true);
+            const examplesOnlyForPublicOrExtern = config.get('examplesOnlyForPublicOrExtern', false);
+            const includeSafetyDetails = config.get('includeSafetyDetails', false);
 
 			if (signature) {
-				const doc = generateDocComment(signature);
+				const doc = generateDocComment(signature, {
+                    includeExamples,
+                    examplesOnlyForPublicOrExtern,
+                    includeSafetyDetails
+                  });
 				if (!doc) return;
 				const item = new vscode.CompletionItem("Generate Rust Doc Comment");
 				item.insertText = new vscode.SnippetString(doc);

src/gen_enum_doc.js

@@ -9,6 +9,8 @@
  * Supports unit variants, tuple variants, and struct variants.
  *
  * @param {string} line - The line containing the Rust `enum` declaration with its body.
+ * @param {boolean} [includeExamples=true] - Whether to include the `# Examples` section.
+ * @param {boolean} [examplesOnlyForPublicOrExtern=false] - If true, include examples only for `pub` or `extern` functions.
  * @returns {string|null} A formatted doc comment block or null if parsing fails.
  */
 function generateEnumDoc(line, includeExamples, examplesOnlyForPublicOrExtern) {

src/gen_fn_doc.js

@@ -13,6 +13,9 @@
  * Tab stops (e.g., `${2:...}`) are included to support editor snippet expansion.
  *
  * @param {string} line - The normalized function signature, stripped of leading comments or extra lines.
+ * @param {boolean} [includeExamples=true] - Whether to include the `# Examples` section.
+ * @param {boolean} [examplesOnlyForPublicOrExtern=false] - If true, include examples only for `pub` or `extern` functions.
+ * @param {boolean} [includeSafetyDetails=false] - Whether to include extended safety rationale in the `# Safety` section.
  * @returns {string|null} The formatted Rust doc comment block as a string, or `null` if the input is not a valid function signature.
  */
 function generateFunctionDoc(line, includeExamples, examplesOnlyForPublicOrExtern, includeSafetyDetails) {

src/gen_struct_doc.js

@@ -16,6 +16,8 @@
  * Tab stops (`${n:...}`) are inserted for editor snippet expansion.
  *
  * @param {string} line - A string containing the full struct declaration, including its body.
+ * @param {boolean} [includeExamples=true] - Whether to include the `# Examples` section.
+ * @param {boolean} [examplesOnlyForPublicOrExtern=false] - If true, include examples only for `pub` or `extern` functions.
  * @returns {string|null} The formatted doc comment block, or `null` if the input is not a valid documentable struct.
  */
 function generateStructDoc(line, includeExamples, examplesOnlyForPublicOrExtern) {

src/test/extension.test.js

@@ -8,7 +8,11 @@ const { findNextSignatureBlock } = require('../utils');
 describe('generateDocComment()', () => {
     it('generates doc for function', () => {
         const input = 'pub fn compute_sum(a: i32, b: i32) -> i32 {';
-        const output = generateDocComment(input);
+        const output = generateDocComment(input, {
+            includeExamples: true,
+            examplesOnlyForPublicOrExtern: false,
+            includeSafetyDetails: true
+          });
         assert.ok(output.includes('# Arguments'));
         assert.ok(output.includes('`a` (`i32`)'));
         assert.ok(output.includes('# Returns'));
@@ -17,28 +21,40 @@ describe('generateDocComment()', () => {
 
     it('generates doc for struct', () => {
         const input = 'pub struct Point { x: f64, y: f64 }';
-        const output = generateDocComment(input);
+        const output = generateDocComment(input, {
+            includeExamples: true,
+            examplesOnlyForPublicOrExtern: false,
+            includeSafetyDetails: true
+          });
         assert.ok(output.includes('# Fields'));
         assert.ok(output.includes('`x` (`f64`)'));
         assert.ok(output.includes('`y` (`f64`)'));
     });
 
     it('generates doc for enum', () => {
         const input = 'enum Color { Red, Green, Blue }';
-        const output = generateDocComment(input);
+        const output = generateDocComment(input, {
+            includeExamples: true,
+            examplesOnlyForPublicOrExtern: false,
+            includeSafetyDetails: true
+          });
         assert.ok(output.includes('# Variants'));
         assert.ok(output.includes('`Red`'));
     });
 
     it('returns null for unsupported input', () => {
-        assert.strictEqual(generateDocComment('trait SomeTrait {}'), null);
+        assert.strictEqual(generateDocComment('trait SomeTrait {}', {
+            includeExamples: true,
+            examplesOnlyForPublicOrExtern: false,
+            includeSafetyDetails: true
+          }), null);
     });
 });
 
 describe('generateFunctionDoc()', () => {
     it('includes async/unsafe modifiers in example block', () => {
         const input = 'pub async unsafe fn risky_call() -> Result<(), Box<dyn Error>> {';
-        const doc = generateFunctionDoc(input);
+        const doc = generateFunctionDoc(input, true, true, true);
         assert.ok(doc.includes('async {'));
         assert.ok(doc.includes('unsafe {'));
         assert.ok(doc.includes('# Safety'));
@@ -47,14 +63,14 @@ describe('generateFunctionDoc()', () => {
 
     it('handles simple function without return', () => {
         const input = 'fn hello(name: &str) {';
-        const doc = generateFunctionDoc(input);
+        const doc = generateFunctionDoc(input, true, true, true);
         assert.ok(doc.includes('`name` (`&str`)'));
         assert.ok(!doc.includes('# Returns'));
     });
 
     it('includes arguments and return section', () => {
         const input = 'pub fn add(a: i32, b: i32) -> i32 {';
-        const output = generateFunctionDoc(input);
+        const output = generateFunctionDoc(input, true, true, true);
         assert.ok(output.includes('# Arguments'), 'Missing arguments section');
         assert.ok(output.includes('`a` (`i32`)'));
         assert.ok(output.includes('`b` (`i32`)'));
@@ -64,74 +80,92 @@ describe('generateFunctionDoc()', () => {
 
     it('handles unsafe functions', () => {
         const input = 'pub unsafe fn access_raw(ptr: *const u8) -> u8 {';
-        const output = generateFunctionDoc(input);
+        const output = generateFunctionDoc(input, true, true, true);
         assert.ok(output.includes('# Safety'), 'Missing safety section');
         assert.ok(output.includes('**This function is `unsafe` because:**'));
         assert.ok(output.includes('Describe unsafe behavior'), 'Missing unsafe placeholder');
     });
 
     it('handles extern functions', () => {
         const input = 'pub extern "C" fn c_func(x: i32) -> i32 {';
-        const output = generateFunctionDoc(input);
+        const output = generateFunctionDoc(input, true, true, true);
         assert.ok(output.includes('# Safety'), 'Missing safety section');
         assert.ok(output.includes('called in the correct program state to avoid UB'), 'Missing UB safety line');
     });
 
     it('handles async functions', () => {
         const input = 'pub async fn fetch_data() -> Result<String, Box<dyn Error>> {';
-        const output = generateFunctionDoc(input);
+        const output = generateFunctionDoc(input, true, true, true);
         assert.ok(output.includes('# Errors'), 'Missing errors section');
         assert.ok(output.includes('fetch_data().await'), 'Missing async example');
     });
 
     it('handles async unsafe extern functions', () => {
         const input = 'pub async unsafe extern "C" fn full_danger() -> Result<(), MyError> {';
-        const output = generateFunctionDoc(input);
+        const output = generateFunctionDoc(input, true, true, true);
         assert.ok(output.includes('# Safety'), 'Missing safety section');
         assert.ok(output.includes('unsafe { full_danger().await }'), 'Missing async unsafe example');
         assert.ok(output.includes('# Errors'), 'Missing errors section');
     });
 
     it('returns null on invalid input', () => {
-        const output = generateFunctionDoc('this is not a function');
+        const output = generateFunctionDoc('this is not a function', true, true, true);
         assert.strictEqual(output, null);
     });
 
 	it('handles pub(crate) visibility', () => {
         const input = 'pub(crate) fn public_function_in_crate() {';
-        const doc = generateFunctionDoc(input);
+        const doc = generateFunctionDoc(input, true, true, true);
         assert.ok(doc.includes('Describe this function'), 'Missing main description');
         assert.ok(doc.includes('# Examples'), 'Missing example section');
     });
 
     it('handles pub(in crate::testing) visibility', () => {
         const input = 'pub(in crate::testing) fn public_function_in_my_mod() {';
-        const doc = generateFunctionDoc(input);
+        const doc = generateFunctionDoc(input, true, true, true);
         assert.ok(doc.includes('Describe this function'), 'Missing main description');
     });
 
     it('handles pub(self) visibility', () => {
         const input = 'pub(self) fn public_function_in_nested() {';
-        const doc = generateFunctionDoc(input);
+        const doc = generateFunctionDoc(input, true, true, true);
         assert.ok(doc.includes('# Examples'), 'Missing example section');
     });
 
     it('handles pub(super) visibility', () => {
         const input = 'pub(super) fn public_function_in_super_mod() {';
-        const doc = generateFunctionDoc(input);
+        const doc = generateFunctionDoc(input, true, true, true);
         assert.ok(doc.includes('Describe this function'), 'Missing placeholder description');
     });
+
+    it('respects includeExamples = false and hides examples section', () => {
+        const input = 'fn private_internal() {}';
+        const doc = generateFunctionDoc(input, false, false, true);
+        assert.ok(!doc.includes('# Examples'), 'Should not include example section for private function');
+    });
+
+    it('respects examplesOnlyForPublicOrExtern = true and hides examples for private function', () => {
+        const input = 'fn private_internal() {}';
+        const doc = generateFunctionDoc(input, true, true, true);
+        assert.ok(!doc.includes('# Examples'), 'Should not include example section for private function');
+    });
+    
+    it('includes examples when examplesOnlyForPublicOrExtern = true and function is pub', () => {
+        const input = 'pub fn exposed() {}';
+        const doc = generateFunctionDoc(input, true, true, true);
+        assert.ok(doc.includes('# Examples'), 'Should include example section for public function');
+    });
 });
 
 describe('generateStructDoc()', () => {
     it('returns null for unit struct', () => {
-        assert.strictEqual(generateStructDoc('struct Empty;'), null);
-        assert.strictEqual(generateStructDoc('struct Nothing {}'), null);
+        assert.strictEqual(generateStructDoc('struct Empty;', true, true), null);
+        assert.strictEqual(generateStructDoc('struct Nothing {}', true, true), null);
     });
 
     it('documents tuple struct', () => {
         const input = 'struct Pair(i32, f64);';
-        const doc = generateStructDoc(input);
+        const doc = generateStructDoc(input, true, false);
         assert.ok(doc.includes('`field_0` (`i32`)'));
         assert.ok(doc.includes('`field_1` (`f64`)'));
         assert.ok(doc.includes('# Examples'));
@@ -146,7 +180,7 @@ describe('generateStructDoc()', () => {
                 p: i32, q: i32, r: i32, s: i32, t: i32
             }
         `;
-        const doc = generateStructDoc(input);
+        const doc = generateStructDoc(input, true, true);
         assert.ok(doc.includes('# Fields'), 'Missing fields section');
         assert.ok((doc.match(/- `/g) || []).length >= 20, 'Should document 20+ fields');
     });
@@ -161,7 +195,7 @@ describe('generateEnumDoc()', () => {
                 Write(String),
             }
         `;
-        const doc = generateEnumDoc(input);
+        const doc = generateEnumDoc(input, true, false);
         assert.ok(doc.includes('`Quit`'));
         assert.ok(doc.includes('`Move { x, y }`'));
         assert.ok(doc.includes('`Write(String)`'));
@@ -170,7 +204,7 @@ describe('generateEnumDoc()', () => {
 
     it('returns null for invalid enum', () => {
         const badEnum = 'enum NotValid';
-        assert.strictEqual(generateEnumDoc(badEnum), null);
+        assert.strictEqual(generateEnumDoc(badEnum, true, true), null);
     });
 
 	it('handles enum with mixed variant types', () => {
@@ -182,7 +216,7 @@ describe('generateEnumDoc()', () => {
 				ChangeColor(i32, i32, i32),
 			}
 		`;
-		const doc = generateEnumDoc(input);
+		const doc = generateEnumDoc(input, true, true);
 		assert.ok(doc.includes('# Variants'), 'Missing variants section');
 		assert.ok(doc.includes('- `Quit`'), 'Missing unit variant');
 		assert.ok(doc.includes('- `Move { x, y }`'), 'Missing struct variant');
@@ -197,7 +231,7 @@ describe('generateEnumDoc()', () => {
                 Field { a: i32, b: i32, c: i32, d: i32, e: i32 }
             }
         `;
-        const doc = generateEnumDoc(input);
+        const doc = generateEnumDoc(input, true, true);
         assert.ok(doc.includes('Tuple(u8, u16, u32, u64, usize)'), 'Missing tuple variant formatting');
         assert.ok(doc.includes('Field { a, b, c, d, e }'), 'Missing field variant formatting');
     });