{"id":20671132,"url":"https://github.com/allnulled/javadoc","last_synced_at":"2025-03-10T17:22:19.038Z","repository":{"id":52126746,"uuid":"132507281","full_name":"allnulled/javadoc","owner":"allnulled","description":"Unopinionated, simple and powerful documentation generator.","archived":false,"fork":false,"pushed_at":"2023-02-06T14:53:16.000Z","size":149,"stargazers_count":5,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-17T18:04:52.709Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/javadoc","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/allnulled.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-07T19:29:32.000Z","updated_at":"2023-07-07T19:09:08.000Z","dependencies_parsed_at":"2023-02-19T09:01:32.366Z","dependency_job_id":null,"html_url":"https://github.com/allnulled/javadoc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allnulled%2Fjavadoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allnulled%2Fjavadoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allnulled%2Fjavadoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allnulled%2Fjavadoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/allnulled","download_url":"https://codeload.github.com/allnulled/javadoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242889642,"owners_count":20201997,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T20:25:22.254Z","updated_at":"2025-03-10T17:22:19.014Z","avatar_url":"https://github.com/allnulled.png","language":"HTML","readme":"# javadoc\n\nUnopinionated, simple and powerful documentation generator.\n\n## Installation\n\n`$ npm i -g javadoc`\n\n## Why?\n\nThis project was created to simplify the documentation of any code that accepts this kind of comments:\n\n```js\n/**\n * \n * Some description here. It accepts (optional) **markdown typing**.\n * \n * @some-property Some value in *markdown*\n * @some-property Some value in *markdown*\n * @some-other-property Some value in *markdown*\n * @some-more-properties Some value in *markdown*\n * The continuation of the value.\n * It can take as much lines as you need.\n * @and-more-properties\n * @and-more\n * @and-more...\n * \n */\n```\n\n## Advantages\n\nThese are some of the advantages of this tool compared to other tools:\n\n  - **Language unopinionated**: it can be used in any programming language project, because:\n     - It uses regular expressions.\n     - It does not parse any source code.\n  - **Glob patterns**: it uses [glob patterns](https://www.npmjs.com/package/glob#glob-primer) to find files.\n  - **Unlimited Javadoc-like tags**: it uses the Javadoc styling but you are free to use any kind of tag, not only a limited set of them.\n  - **JSON or Markdown output**: it can extract Javadoc comments in:\n     - **JSON**: to abstractly program the views of your own project.\n     - **Markdown**: to directly use the comments in a typical *README.md* file, or similar.\n  - **CLI or API**: it has a command-line interface and an abstract programming interface, and both work almost the same way.\n\n\n## CLI usage\n\nAs simple as:\n\n```sh \n$ javadoc\n  --include \"**/*.js\" \"**/*.ts\"\n  --exclude \"**/node_modules/**\" \"**ignore**\"\n  --format markdown\n  --output README.md\n```\n\nOr abbreviatedly:\n\n```sh\n$ javadoc\n  -i \"**/*.php\" \"**/*.sql\"\n  -e \"**/node_modules/**\" \"**ignore**\"\n  -f json\n  -o README.md\n```\n\nType `javadoc --help` to see the help.\n\n## API usage\n\n```js\nrequire(\"javadoc\").generate({\n    include: [\"**/*.js\", \"**/*.ts\"],\n    exclude: [\"**/node_modules/**\"],\n    format: \"markdown\",\n    output: \"README.md\"\n}).then(report =\u003e {\n    // manage a report of success and errors...\n}).catch(error =\u003e {\n    // manage the error...\n});\n```\n\n## API reference\n\nHere you will find the whole API available for programmatic usage, documented.\n\n*Note: the main interesting method is `Javadoc.generate`, which is the one called by the **CLI**.*\n\n\n-----------------\n\n### `Javadoc`\n\n\n**Type**:  *Class. Function.*\n\n\n**Description**:  Master class of the `javadoc` package.\n\n\n\n-------------------\n\n### `Javadoc.REGEX_PATTERNS`\n\n\n**Type**:  *Static property. Object.*\n\n\n**Description**:  Regular expression patterns used by the class.\n\n\n\n-------------------------\n\n### `Javadoc.DEFAULT_GLOB_OPTIONS`\n\n\n**Type**:  *Static property. Object.*\n\n\n**Property**:  \n\n\n - `cwd`. Defaults to `process.cwd()`. Allowed options at [glob package](https://www.npmjs.com/package/glob#options)\n\n\n - `dot`. Defaults to `true`. Allowed options at [glob package](https://www.npmjs.com/package/glob#options)\n\n\n**Description**:  Default options used by the `glob` package.\n\n\n\n---------------------------\n\n### `Javadoc.DEFAULT_OPTIONS`\n\n\n**Type**:  *Static property. Object.*\n\n\n**Property**:  \n\n\n - `include:Array\u003cString\u003e`. Defaults to `[\"**/*.js\"]`. Allowed rules at [glob package](https://www.npmjs.com/package/glob).\n\n\n - `exclude:Array\u003cString\u003e`. Defaults to `[\"**/node_modules/**.js\"]`. Allowed rules at [glob package](https://www.npmjs.com/package/glob).\n\n\n - `format:String`. Defaults to `\"markdown\"`. Allowed values:\n    - `\"md\"`\n    - `\"json\"`\n\n\n - `output:String`. Defaults to `undefined`. File into which dump the results. **Required value**.\n\n\n**Description**:  General options of the `Javadoc.generate` main method.\n\n\n\n------------------------\n\n### `Javadoc.findFiles`\n\n\n**Type**:  *Static method. Function.*\n\n\n**Parameter**:  \n\n\n - `parameterIncludes:Array\u003cString\u003e`. Replaces `DEFAULT_OPTIONS.include` as value.\n\n\n - `parameterExcludes:Array\u003cString\u003e`. Replaces `DEFAULT_OPTIONS.exclude` as value.\n\n\n - `parameterOptions:Object`. Overrides `DEFAULT_GLOB_OPTIONS` as object.\n\n\n**Returns**:  files:Promise\u003cArray\u003cString\u003e\u003e. Asynchronously, returns an array of matched files (as Strings).\n\n\n**Description**:  Finds files based on glob patterns ([more info](https://www.npmjs.com/package/glob#usage)) included, excluded and glob options ([more info](https://www.npmjs.com/package/glob#options)).\n\n\n\n-------------------------------\n\n### `Javadoc.findCommentsInFile`\n\n\n**Type**:  *Static method. Function.*\n\n\n**Parameter**:  `file:String`. File into which look for the javadoc-comments.\n\n\n**Returns**:  `matches:Promise\u003cArray\u003cObject\u003e\u003e`. Asynchronously, returns a list of matched javadoc-comments (as Objects) found in the passed file.\n\n\n**Description**:  From a file, it returns (asynchronously, by a Promise) javadoc-comments represented as Objects.\n\n\n\n--------------------------------\n\n### `Javadoc.findCommentsInString`\n\n\n**Type**:  *Static method. Function.*\n\n\n**Parameter**:  `text:String`. Text into which look for the javadoc-comments.\n\n\n**Returns**:  `totalMatches:Array\u003cObject\u003e`. List of javadoc-comments (as Objects) found in the passed String.\n\n\n**Description**:  Finds javadoc-comments (as Objects) from a String.\n\n\n\n-----------------------------------\n\n### `Javadoc.formatJsonToMarkdown`\n\n\n**Type**:  *Static method. Function.*\n\n\n**Parameter**:  `fileComments:Array\u003cObject\u003e`. List of javadoc-comments (as Object) to convert to markdown format.\n\n\n**Returns**:  `formatted:String`. Markdown code from passed javadoc-comments.\n\n\n**Description**:  Generates `markdown` code from a list of javadoc-comments.\n\n\n\n-----------------------------------\n\n### `Javadoc.generate`\n\n\n**Type**:  *Static method. Function.*\n\n\n**Parameter**:  `parameters:Object`. Overrides `Javadoc.DEFAULT_OPTIONS` as Object. To see more about properties, go to that static property of Javadoc class.\n\n\n**Returns**:  `output:Promise\u003cString|Array\u003cObject\u003e\u003e`. Depending on `parameters.format` (`\"json\"`|`\"markdown\"`), it can return an Array or a String.\n\n\n**Description**:  Finds included files, dismisses excluded files, extracts javadoc-comments, formats them adecuately, and dumps the results into output file, while returning the output asynchronously (as a Promise).\n\n\n\n\n----------------\n\n## Tests\n\nTo run the test, clone the repository and run `npm run test`.\n\n## Coverage\n\nTo run the coverage test, clone the repository and run `npm run cover`.\n\n## License\n\nThis project is licensed under [WTFPL](https://es.wikipedia.org/wiki/WTFPL), which stands for *Do What The Fuck You Want To Public License*.\n\n## Versioning\n\nThis project adheres to [semantic versioning 2.0](https://semver.org/).\n\n## Issues\n\nTo communicate issues [here](https://github.com/allnulled/javadoc/issues/new).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallnulled%2Fjavadoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fallnulled%2Fjavadoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallnulled%2Fjavadoc/lists"}