diff options
| -rw-r--r-- | README.md | 104 | ||||
| -rw-r--r-- | src/init.lua | 21 |
2 files changed, 71 insertions, 54 deletions
@@ -1,52 +1,52 @@ -# MDoc
-
-## Overview
-
-A documentation engine for Lua
-
-MDoc was built after frustrations with
-[LDoc](https://stevedonovan.github.io/ldoc/manual/doc.md.html),
-the usual and most popular documentation engine for lua. Like LDoc, MDoc uses
-comments in the source code to generate html files for documentation. Unlike
-LDoc, it makes no attempts to be backwards compatible with LuaDoc. This results
-in a documentation engine that is free from constraints like "One class per
-file" or "one module per file", and allows for an architecture that is more
-consistent and elegent overall. MDoc is still in it's early stages, expect
-frequent code churn in the near future.
-
-MDoc is used to document my homebrew game engine and VR platform, [Brok\[en\]gine](https://cogarr.net/source/cgit.cgi/brokengine/),
-and you can see an example of mdoc in action at the [Brok\[en\]gine reference](https://cogarr.net/brokengine/).
-
-## Installation
-
-The easiest way to download MDoc is with [luarocks](https://github.com/luarocks/luarocks)
-
-```
-luarocks install --server=http://rocks.cogarr.net mdoc
-```
-
-## Usage
-
-`mdoc` or `mdoc --help` prints help information:
-
-```
-mdoc -p <folder> [-p <folder> ...][ -o <folder>][ -t "title"][ -i <file>][ -d <folder>[ -d <folder> ...]][ -m <executable>][ -h]
-
- -p | --path <folder> : Path to search for source files
- -o | --output <folder> = "." : Folder to output HTML files to (and a cache folder)
- -t | --title "name" = "Mdoc Generated Page" : Title for the html files
- -i | --index <file> : File to use for the index file
- -d | --document <folder> : Path to search for files to put inder the References section
- -m | --markup-parser <executable> : Executable to use to parse the descriptions and refrence documents.
- Executable should accept a file path as it's argument, and generate html as it's output.
- -h | --help : print this help
- -v | --verbose : print extra information during run
- -c | --no-cache : rebuild files, even if they're not out of date.
-```
-
-## Bugs
-
-Please report bugs or mail patches to [alex@cogarr.net](mailto://alex@cogarr.net)
-
-You can find instructions for creating patches [here](https://cogarr.net/source/cgit.cgi/?p=about)
-
+# MDoc + +## Overview + +A documentation engine for Lua + +MDoc was built after frustrations with +[LDoc](https://stevedonovan.github.io/ldoc/manual/doc.md.html), +the usual and most popular documentation engine for lua. Like LDoc, MDoc uses +comments in the source code to generate html files for documentation. Unlike +LDoc, it makes no attempts to be backwards compatible with LuaDoc. This results +in a documentation engine that is free from constraints like "One class per +file" or "one module per file", and allows for an architecture that is more +consistent and elegent overall. MDoc is still in it's early stages, expect +frequent code churn in the near future. + +MDoc is used to document my homebrew game engine and VR platform, [Brok\[en\]gine](https://cogarr.net/source/cgit.cgi/brokengine/), +and you can see an example of mdoc in action at the [Brok\[en\]gine reference](https://docs.cogarr.net/brokengine/). + +## Installation + +The easiest way to download MDoc is with [luarocks](https://github.com/luarocks/luarocks) + +``` +luarocks install --server=http://rocks.cogarr.net mdoc +``` + +## Usage + +`mdoc` or `mdoc --help` prints help information: + +``` +mdoc -p <folder> [-p <folder> ...][ -o <folder>][ -t "title"][ -i <file>][ -d <folder>[ -d <folder> ...]][ -m <executable>][ -h] + + -p | --path <folder> : Path to search for source files + -o | --output <folder> = "." : Folder to output HTML files to (and a cache folder) + -t | --title "name" = "Mdoc Generated Page" : Title for the html files + -i | --index <file> : File to use for the index file + -d | --document <folder> : Path to search for files to put inder the References section + -m | --markup-parser <executable> : Executable to use to parse the descriptions and refrence documents. + Executable should accept a file path as it's argument, and generate html as it's output. + -h | --help : print this help + -v | --verbose : print extra information during run + -c | --no-cache : rebuild files, even if they're not out of date. +``` + +## Bugs + +Please report bugs or mail patches to [alex@cogarr.net](mailto://alex@cogarr.net) + +You can find instructions for creating patches [here](https://cogarr.net/source/cgit.cgi/?p=about) + diff --git a/src/init.lua b/src/init.lua index fc57f24..bc921f2 100644 --- a/src/init.lua +++ b/src/init.lua @@ -1,10 +1,10 @@ #!/usr/bin/env lua --[[ -Mdoc creats documentation from comments in source files. +Mdoc creates documentation from comments in source files. Mdoc works in several steps: 1. Create "chunks" from input source files - 2. Create a dependnecy graph, so we only update the things that + 2. Create a dependency graph, so we only update the things that need updating 3. Output html documentation ]] @@ -13,6 +13,9 @@ local et = require("etlua") require("mdoc.ext") local opt = require("mdoc.opt") +--[[ +Parse arguments, if we can't run this tool, print a help menu and exit +]] local args = {...} local options = opt.parse_options(args) if options.help then @@ -215,6 +218,15 @@ local parse_between = { ["/***"] = "*/", ["--[[**"] = "]]" } +local comment_parsers = { + "doc.short_desc", + "doc.desc", + "doc.function", + "doc.tparam", + "doc.treturn" + "doc.method", + "doc.field", +} for _,file in pairs(state.files) do local cachefilename = string.format("%s/cache/files/%s",options.output,file.relpath) local cacheattrs = lfs.attributes(cachefilename) @@ -257,6 +269,11 @@ end for _,file in pairs(state.files) do local function process_chunk(chunk) assert(chunk.file and chunk.line, "Chunk without file or line num:") + local state = { + short_desc = "no short description provided", + desc = {}, + + } local section = nil local partname = nil local sectiontype = nil |