{"id":13895995,"url":"https://github.com/lua-rocks/luapi","last_synced_at":"2025-07-17T11:32:53.001Z","repository":{"id":218915778,"uuid":"366676950","full_name":"lua-rocks/luapi","owner":"lua-rocks","description":"Documentation generation with Lua","archived":true,"fork":false,"pushed_at":"2021-07-04T14:41:04.000Z","size":294,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2024-08-07T18:37:31.985Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":false,"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/lua-rocks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-05-12T10:25:39.000Z","updated_at":"2023-01-28T07:58:18.000Z","dependencies_parsed_at":"2024-01-24T14:11:45.310Z","dependency_job_id":null,"html_url":"https://github.com/lua-rocks/luapi","commit_stats":null,"previous_names":["lua-rocks/luapi"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lua-rocks%2Fluapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lua-rocks%2Fluapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lua-rocks%2Fluapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lua-rocks%2Fluapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lua-rocks","download_url":"https://codeload.github.com/lua-rocks/luapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226260601,"owners_count":17596494,"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-08-06T18:02:36.147Z","updated_at":"2024-11-25T01:30:55.510Z","avatar_url":"https://github.com/lua-rocks.png","language":"Lua","funding_links":[],"categories":["Lua"],"sub_categories":[],"readme":"# LUAPI (WIP)\n\n## Important announcement\n\nThe development of this project did not stop!\nI just decided to rewrite everything from scratch again in OOP style\nand combine it together with some other very userful libs.\n\n**[\u003e\u003e NEW REPOSITORY IS HERE \u003c\u003c](https://github.com/lua-rocks/core)**\n\n## Description\n\n**LUAPI** is an attempt to bring together the best features of all lua\ndocumentation tools I know, such as: [ldoc][], [luadoc][], [emmylua][] and\n[scriptum][].\n\nIn my work I try to adhere to the [KISS][] principle, so that documenting your\ncode and modifying the source code for this utility should not cause\ndifficulties for anyone (but knowledge of the lua pattern matchers is still\nrequired if you want to modify parser).\n\nThis repository was originally forked from `scriptum`, but I rewrote it\ncompletely, so now there is little in common between `scriptum` and `luapi`.\n\n## Similarities and differences\n\n- Just like `scriptum`, `luapi` generates markdown documentation that you can\n  easily convert to any other format, styling it as you like, or post on\n  github/bitbucket etc, or just view it through a browser using the .md file\n  viewer extension. Even in notepad, this documentation is quite readable.\n- Unlike `scriptum`, `luapi` keeps all file in one string when parsing it and\n  search patterns in this string or its chunks, but not loops through each\n  line and it also writes each file only once so it should be much faster.\n- Unlike most analogs, you are not required to memorize a set of tags and\n  complex rules for their use. My tool is extremely simple! It only uses 2\n  single-character tags and 2 kinds of brackets:\n  - `\u003e`: function argument or table field\n  - `\u003c`: function return or describing table as class\n  - `(parentheses)`: the type or parent class of the variable\n  - `[square brackets]`: default value of the variable (makes it _optional_)\n  - Quick example:\n  ```lua\n  --[[ Some function title\n  Some function comment.\n  Can be multiline.\n  _Support_ **markdown**.\n  \u003e str (string) some string comment\n  \u003e num (number) [2] some number comment\n  \u003c con (string) result of concatenation\n  ]]\n  local function example(str, num)\n    num = num or 2\n    return str .. num\n  end\n  ```\n- I don't have tags like `@author` or `@copyright` because you can markdown this\n  information inside module comments, and those tags are just garbage.\n- Like `emmylua`, I plan to implement smart hints for the `atom` editor. Perhaps\n  the list of editors will expand, but at the moment even `atom` is not\n  supported yet, so it's too early to promise anything.\n- Unlike `scriptum` and like `ldoc`, only **external** module fields and methods\n  will be written to markdown, but internal tables and functions still parsed\n  and can be used for smart hints in IDE or somewhere else.\n- Like `ldoc`, if your tags mismatch with real params or if you started comment\n  block but not commented some params, you will get warnings in the terminal.\n- Keep in mind that my project is still very young and poorly tested, so bugs\n  are common at this stage.\n\n## Types\n\nWhen declaring a variable type, you can use all the built-in lua types or actual\nvariable values, plus the types listed below:\n\n- **any** for any type\n- **integer** for non float number\n- **list** for tables with integer keys\n- **{string=number}** for table with **one** key=value\n- **{1=string,\"size\"=32}** similar example for 2 values\n- **{string=string...}** any number of string key/values\n- **{integer=any...}** this example is equivalent to **list**\n\nAlso you can use your defined classnames or module require paths as types.\n\nDon't use spaces as separators in type definitions.\n\n## Todo\n\n- File can have one external class and many internals (tables as classes).\n  - Totally ignore internal tables and functions.\n    - Remove `file.tables`, `file.functions`, `module.params`.\n    - Add `module.fields`, `module.methods`, `file.classes`.\n  - Add posibility to describe nonexistent fields, methods, classes.\n- Escape whatever you want with `\\` (partitially done).\n- Update comments in sources.\n- Document `do ... end` blocks as sections.\n- Unpack (`@`).\n  - I like the idea of `scriptum`:`unpack` but it is not implemented yet.\n  - Unpack should work with params and returns in any scope.\n    Like this: `\u003e @conf` or `\u003c @conf`.\n- Lua files in `doc` folder automaticaly includes in md-files as examples.\n- Suppport for OOP: inheritance.\n- Add support for [atom-autocomplete][].\n- Clean markdown: no [markdownlint][] warnings.\n- Combine all modules into one file and remove debug garbage.\n- Squash my crazy commits.\n- Publish to luarocks.\n\n## Style guide\n\nThese rules are _optional_, but highly recommended:\n\n- Maximum line number is **80** characters.\n- `One line` **title** comments must start with **uppercase** letter.\n- `One line` **parameter** comments must start with a **lowercase**.\n- `One line` (**any**) comments must **not** have a dot or semicolon at the end.\n- `Muliline` (**any**) comments must **have** a dot or semicolon at the end.\n\nOf course, I can correct everything automatically in docgen, but don't forget\nthat your source code is also a documentation!\n\n[KISS]: https://en.wikipedia.org/wiki/KISS_principle\n[ldoc]: https://stevedonovan.github.io/ldoc/manual/doc.md.html\n[luadoc]: https://keplerproject.github.io/luadoc\n[scriptum]: https://github.com/charlesmallah/lua-scriptum\n[emmylua]: https://github.com/EmmyLua\n[markdownlint]: https://github.com/DavidAnson/markdownlint\n[atom-autocomplete]: https://github.com/dapetcu21/atom-autocomplete-lua\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flua-rocks%2Fluapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flua-rocks%2Fluapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flua-rocks%2Fluapi/lists"}