{"id":20287267,"url":"https://github.com/cancerberosgx/javascript-documentation-examples","last_synced_at":"2025-04-11T09:40:55.261Z","repository":{"id":141927015,"uuid":"130640101","full_name":"cancerberoSgx/javascript-documentation-examples","owner":"cancerberoSgx","description":"JavaScript (and its family) has no standard tool for documentation and there are many tools with different perspective. This is a collection of working node.js projects demonstrating best practices of complex semantics in such tools","archived":false,"fork":false,"pushed_at":"2018-05-12T17:28:52.000Z","size":954,"stargazers_count":10,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-25T06:41:25.041Z","etag":null,"topics":["documentation","javadoc","javascript","jsdoc","short-jsdoc","typedoc","typescript"],"latest_commit_sha":null,"homepage":null,"language":null,"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/cancerberoSgx.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-23T04:29:32.000Z","updated_at":"2025-01-21T03:54:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"b83cb7fb-ed98-456a-b191-31bc0ded0661","html_url":"https://github.com/cancerberoSgx/javascript-documentation-examples","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/cancerberoSgx%2Fjavascript-documentation-examples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cancerberoSgx%2Fjavascript-documentation-examples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cancerberoSgx%2Fjavascript-documentation-examples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cancerberoSgx%2Fjavascript-documentation-examples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cancerberoSgx","download_url":"https://codeload.github.com/cancerberoSgx/javascript-documentation-examples/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248369056,"owners_count":21092513,"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":["documentation","javadoc","javascript","jsdoc","short-jsdoc","typedoc","typescript"],"created_at":"2024-11-14T14:39:10.117Z","updated_at":"2025-04-11T09:40:55.253Z","avatar_url":"https://github.com/cancerberoSgx.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# About\n\nJavaScript (and its family) has no standard tool for documentation and there are many tools with different perspective. This is a collection of working node.js projects demonstrating best practices of complex semantics in such tools. \n\n\n# Success experiments\n\n A list of expeiments that IMO demonstrate best practices for documentation\n\n## TypeDoc tutorial\n\n TypeDoc is a great tool but with very poor documentation, this is my attempt to solve that: [TypeDoc Tutorial](https://cancerberosgx.github.io/javascript-documentation-examples/examples/typedoc-tutorial-basic/docs/docco/src/index.html)\n\n\n## events-002\n\nDemonstrate best practices for documenting events, after some failures, I concluded that I needed a typedoc plugin for accomplish the perfect representation of events. So I implemented [as-member-of](https://github.com/cancerberoSgx/typedoc-plugins-of-mine/tree/master/plugins/typedoc-plugin-as-member-of) type-doc plugin and declaring events as separate functions. The following tutorial explains with detail:  \n\n#### [Tutorial, descriptions and code](https://cancerberosgx.github.io/javascript-documentation-examples/examples/events-002/docs/docco/src/index.html)\n\n\n#### [Final Output](https://cancerberosgx.github.io/javascript-documentation-examples/examples/events-002/docs/interfaces/vehicle.html)\n\n\n\n\n# Failed experiments\n\nThe following are the examples generated that I consider failures this is , they are non-satisfactory experiments or demonstrate tools limitations. \n\n## events-001 (failed)\n\nSeveral (failed) experiments trying to document events with typedoc, particularly subclasses of node.js `EventEmitter`.\n\n#### [Tutorial, descriptions and code](https://cancerberosgx.github.io/javascript-documentation-examples/examples/events-001/docs/docco/src/index.html)\n\n#### [Final Output](https://cancerberosgx.github.io/javascript-documentation-examples/examples/events-001/docs/interfaces/idownloadeventemitter.html#on)\n\n\n## events-noEventEmitter (failed)\n\nSimilar example as [events-001](https://cancerberosgx.github.io/javascript-documentation-examples/examples/events-001/docs/docco/src/index.html) Nothing special here. But completly indepdent of EventEmitter and declaring a righ class hierarchy of Listeners, EventSources, etc. \nBest practices for documenting events, particularly subclasses of node.js `EventEmitter`\n\n#### [Tutorial, descriptions and code](https://cancerberosgx.github.io/javascript-documentation-examples/examples/events-noEventEmitter/docs/docco/src/index.html)\n\n#### [Final Output](https://cancerberosgx.github.io/javascript-documentation-examples/examples/events-noEventEmitter/docs/interfaces/igenericdeviceeventsource.html#adddevicelistener)\n\n\n\n\n\n# Install and generate all the docs\n\n```sh\nyarn \nyarn run-all doc\n```\n\nNote with `yarn run-all X` you run X command in all yarn workspaces\n\n\n\n# Concepts and technologies\n\nSome concepts that are hard to document (I'm learning and discussing best practices in this project) : \n\n * Events EventEmitters and EventListeners particularly best practices for descibing complex hierarchies.\n \nSome technologies: \n\n * jsdoc (and templates)\n * typedoc (and templates)\n * short-jsdoc\n * JavaScript\n * TypeScript\n * Flow\n\n\n# TODO: things I don't know how to do, yet\n\n## typedoc\n\n * \"this method trigger the event foo of that class\". can do it in jsdoc but not in typedoc\n\n*\n    // TODO: IDEA: what if we biuld a event emitter with generics that doesn't \n    // extends node event emitter but just delegate the methods to a property???","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcancerberosgx%2Fjavascript-documentation-examples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcancerberosgx%2Fjavascript-documentation-examples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcancerberosgx%2Fjavascript-documentation-examples/lists"}