{"id":21141604,"url":"https://github.com/bjornbytes/docroc","last_synced_at":"2025-07-09T05:32:01.546Z","repository":{"id":144340160,"uuid":"41196326","full_name":"bjornbytes/docroc","owner":"bjornbytes","description":"Lua comments go in, documentation comes out.","archived":false,"fork":false,"pushed_at":"2015-12-25T21:35:49.000Z","size":7,"stargazers_count":12,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-05-02T00:43:27.586Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bjornbytes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-22T07:31:50.000Z","updated_at":"2023-05-11T17:16:10.000Z","dependencies_parsed_at":"2023-03-21T22:14:43.119Z","dependency_job_id":null,"html_url":"https://github.com/bjornbytes/docroc","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjornbytes%2Fdocroc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjornbytes%2Fdocroc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjornbytes%2Fdocroc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjornbytes%2Fdocroc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bjornbytes","download_url":"https://codeload.github.com/bjornbytes/docroc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225486687,"owners_count":17481949,"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-20T07:32:20.602Z","updated_at":"2024-11-20T07:32:21.358Z","avatar_url":"https://github.com/bjornbytes.png","language":"Lua","funding_links":[],"categories":["资源","Resources"],"sub_categories":["Documentation"],"readme":"docroc\n===\n\nMinimal library that parses formatted Lua comments and returns them as a table.\n\nUsage\n---\n\n```lua\nlocal docroc = require 'docroc'\nlocal comments = docroc.process('file.lua')\n```\n\n`comments` is now a table of comment blocks in the file, each with a table of `tags` and a `context`\nkey. The `tags` table is an array of the tags, but also groups the tags by type. The `context` key\nis a string containing the contents of the line after the comment block.\n\nNotes on parsing:\n\n- A comment block must start with three dashes. It ends on the next non-commented line.\n- Tags are recognized as any sequence of letters that start with `@`, and continue until the next\ntag is encountered. The first tag is implicitly `@description`.\n\nExample\n---\n\nGo from this:\n\n```lua\n--- Displays a friendly greeting.\n-- @arg {string=} name - The person to greet.\n-- @returns {number}\nfunction greet(name)\n  print('hi', name)\n  return 3\nend\n```\n\nto this:\n\n```lua\n{\n  {\n    context = 'function greet(name)',\n    tags = {\n      [1] = {\n        tag = 'description',\n        text = 'The person to greet.'\n      },\n      [2] = {\n        tag = 'arg',\n        text = '{string=} name - The person to greet',\n        type = 'string',\n        optional = true,\n        name = 'name',\n        description = 'The person to greet.'\n      },\n      [3] = {\n        tag = 'returns',\n        text = '{number}',\n        type = 'number'\n      },\n      description = {...},\n      arg = {...},\n      returns = {...}\n    }\n  }\n}\n```\n\nProcessors\n---\n\nBy default, when docroc finds a tag, it creates an entry with two keys: `tag` and `text`.  `tag`\ncontains the name of the tag and `text` contains the text after the tag.  This behavior can be\nextended using the `docroc.processors` table:\n\n```lua\ndocroc.processors.customTag = function(body)\n  return {\n    numberOfCharacters = #body,\n    reversed = body:reverse()\n  }\nend\n```\n\nNow, if we process a file containing the following:\n\n```lua\n--- @customTag hello world\nlocal test\n```\n\nWe would get this:\n\n```lua\n{\n  tag = 'customTag',\n  text = 'hello world',\n  numberOfCharacters = 11,\n  reversed = 'dlrow olleh'\n}\n```\n\nFor convenience, docroc provides a default set of custom processors:\n\n- `@arg`: Collects information on an argument to a function, including the `type` of the argument,\nwhether or not it is `optional`, whether or not it has a `default` value, its `name`, and a\n`description`.  The expected structure is `@arg {\u003ctype\u003e=\u003cdefault\u003e} \u003cname\u003e - \u003cdescription\u003e`, all of\nwhich are optional.  An equals sign after the type represents an optional argument.\n- `@returns`: Similar to `@arg`, contains information on a return value of the function.  It\nreturns `type` and `description` keys, and expects a structure of `@returns {\u003ctype\u003e} \u003cdescription\u003e`.\n\nRelated\n---\n\n- [Locco](http://rgieseke.github.io/locco)\n- [LDoc](https://github.com/stevedonovan/LDoc)\n\nLicense\n---\n\nMIT, see [`LICENSE`](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjornbytes%2Fdocroc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbjornbytes%2Fdocroc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjornbytes%2Fdocroc/lists"}