ploc

library0.9.1jsnpmunverified

A simple PL/SQL code-to-document converter that extracts specially formatted PL/SQL comments and generates Markdown documentation files. Current stable version is 0.9.1, released on npm and written in JavaScript. It is a lightweight tool (around 120 lines of code) that supports packages, functions, procedures, types, and triggers. Key differentiators: focuses solely on PL/SQL-to-Markdown conversion with minimal configuration, supports table of contents generation, and integrates with file watchers for automated documentation updates. Compared to PLDoc or other PL/SQL doc generators, PLOC is deliberately minimal and requires explicit comment markers (`/** ... **/`) for documentation extraction.

devops

npm install ploc

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PLOC

ploc

devopsjavascriptv0.9.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ploc

✓ import { ploc } from 'ploc'

✗ const ploc = require('ploc')

The package is ESM-only. Named export 'ploc' is a function that converts a PL/SQL source string to Markdown.

ploc (default import)

✓ import ploc from 'ploc'

✗ import { default as ploc } from 'ploc'

Default import also works and exports the same function as named.

PlocOptions

✓ import type { PlocOptions } from 'ploc'

Type import for TypeScript users (shipped with types).

Converts a PL/SQL source string containing specially commented items into Markdown documentation.

import { ploc } from 'ploc'; const plsqlSource = ` CREATE OR REPLACE PACKAGE demo AUTHID current_user IS /** My Package ========== This is a demo package. **/ FUNCTION hello RETURN VARCHAR2; /** Returns a greeting. **/ END demo; `; const md = ploc(plsqlSource, { toc: true }); console.log(md);

Debug

Known issues

gotchaOnly comments starting with /** and ending with **/ (double asterisks) are recognized. Regular /* ... */ comments are ignored.

fix

Ensure all documentation comments use the /** ... **/ syntax instead of /* ... */.

affects: >=0.9.1

gotchaTable of contents (TOC) is only generated when the number of documented items exceeds a configurable threshold (default 3).

fix

Set the `toc` option to `true` or adjust the `tocMinItems` threshold.

affects: >=0.9.1

deprecatedCommonJS require() is not supported. The package is ESM-only.

fix

Use ESM import syntax: `import { ploc } from 'ploc'`.

affects: >=0.9.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

The file is not treated as an ES module (needs "type": "module" in package.json or .mjs extension).

fix

Add "type": "module" to your package.json or rename the file to .mjs.

TypeError: ploc is not a function

Importing incorrectly: using default import when the package exports named export only (or vice versa).

fix

Use either `import ploc from 'ploc'` or `import { ploc } from 'ploc'`.

Error: Missing closing **/ for comment starting at line X

A documentation comment (/** ... **/) is not properly closed with **/.

fix

Ensure every /** comment is terminated with **/ (double asterisk slash, not just */).

Warning: No PL/SQL items found in source.

Source does not contain any recognized PL/SQL objects (PACKAGE, FUNCTION, PROCEDURE, TYPE, TRIGGER) with a following /** comment.

fix

Verify that your PL/SQL code includes at least one supported object with a documentation comment immediately after the signature.

Upgrade

Version history

0.9.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/ogobrecht/ploc ↗

packageploc ↗

homepagehttps://github.com/ogobrecht/ploc#readme ↗