-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'master' of https://github.com/DanielSWolf/MoaiUtils
- Loading branch information
Showing
1 changed file
with
46 additions
and
27 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,48 +1,67 @@ | ||
| # MoaiUtils | ||
|
|
||
| Utilities for the Moai SDK | ||
| _Utilities for the Moai SDK_ | ||
|
|
||
| At one point, MoaiUtils will become a collection of useful command-line utilities for people using the [Moai SDK](http://getmoai.com/). For now, it consists of a single tool, CreateApiDescription. | ||
| MoaiUtils is a collection of useful command-line utilities to use with the [Moai SDK](http://getmoai.com/). For now, it consists of two tools: [DocExport](#docexport) and [DocLint](#doclint). | ||
| MoaiUtils is open source; a pre-compiled version can be downloaded on the [releases site](https://github.com/DanielSWolf/MoaiUtils/releases). | ||
|
|
||
| ## CreateApiDescription.exe | ||
| ## DocExport | ||
|
|
||
| Given a local copy of the Moai source code, this tool will extract all kinds of information from the code and its comments. It will then generate a code-completion file for [ZeroBrane Studio](http://studio.zerobrane.com/). Using this file, you'll get far superior code completion for Moai than with the built-in support. For a detailed description with screenshots, see the [Moai forum entry]( http://getmoai.com/forums/moaiutils-1-0-better-code-completion-in-zerobrane-t2473/#p12878). | ||
| DocExport analyzes Moai's C++ source code and extracts the code comments documenting the Lua API. This information can then be exported to a number of formats, usually to create code-completion files for text editors. | ||
|
|
||
| ### How to use | ||
| ### Creating a documentation file | ||
|
|
||
| 1. Download MoaiUtils | ||
| DocExport supports the following command-line arguments: | ||
|
|
||
| Download MoaiUtils.zip from the [current release of MoaiUtils](https://github.com/DanielSWolf/MoaiUtils/releases) and unpack it. | ||
| * `-i`, `--input` The Moai base directory. | ||
| * `-o`, `--output` The output directory where the code completion file(s) will be created. | ||
| * `-f`, `--format` The export format. Valid options are `ZeroBrane`, `SublimeText`, or `XML`. For a description of these formats, see below. | ||
|
|
||
| 2. Run CreateApiDescription | ||
| On Windows, a typical invocation will look like this: `DocExport.exe -i "D:\moai-dev" -o "D:\temp" -f ZeroBrane`. | ||
| If you're on something other than Windows (i.e., Linux or OS X), you can run the tool using [Mono](http://www.mono-project.com/Main_Page). There's no need to recompile. Just run `mono DocExport.exe <arguments>`. | ||
|
|
||
| Point the tool to your local Moai source directory and tell it where to create its output. On Windows, a typical invocation will look like this: `CreateApiDescription.exe -i "D:\moai-dev\src" -o "D:\temp"`. For a complete list of command-line options, see below. | ||
| If you're on something other than Windows (i.e., Linux or OS X), you can run the tool using [Mono](http://www.mono-project.com/Main_Page). There's no need to recompile or anything. Just run `mono CreateApiDescription.exe <arguments>`. | ||
| ### Documentation file formats | ||
|
|
||
| This will create a file called moai.lua containing all code completion information. | ||
| #### ZeroBrane Studio | ||
|
|
||
| 3. Replace the code-completion file | ||
| DocExport can create code-completion files for [ZeroBrane Studio](http://studio.zerobrane.com/), a great Lua IDE (donationware). This gives ZeroBrane Studio full access to all of Moai's classes, fields and methods, along with overloads, return values, and full documentation. For some screenshots, see this (otherwise dated) [Moai forum entry]( http://getmoai.com/forums/moaiutils-1-0-better-code-completion-in-zerobrane-t2473/#p12878) for MoaiTools 1.0. | ||
|
|
||
| ZeroBrane Studio already ships with a moai.lua file in `ZeroBraneStudio\api\lua`. Just replace it with the new one and you're done! | ||
| ##### How to use | ||
|
|
||
| 4. Enjoy! :-) | ||
| ZeroBrane Studio already ships with a `moai.lua` file in `ZeroBraneStudio\api\lua`. Just replace it with the new one. | ||
|
|
||
| Tip: By default, ZeroBrane Studio only shows the first few lines of the help text. To see the entire documentation, press Ctrl+T (as in tooltip). | ||
| _Tip:_ By default, ZeroBrane Studio only shows the first few lines of the help text. To see the entire documentation, press `Ctrl+T` (as in tooltip). | ||
|
|
||
| ### Command-line options | ||
| #### Sublime Text | ||
|
|
||
| * `-i`, `--input` | ||
| [Sublime Text](http://www.sublimetext.com/) is a powerful text editor, but has no understanding of Lua code. Thus, code completion in Sublime Text is rather limited compared to ZeroBrane Studio. | ||
|
|
||
| Required. The Moai `src` directory. | ||
| ##### How to use | ||
|
|
||
| * `-o`, `--output` | ||
| Place the generated `moai_lua.sublime-completions` file anywhere in your `Packages` folder, ideally inside of `/Lua`. You can open the packages folder from Sublime Text via the menu option "Preferences" >"Browse Packages". Depending on the version of Sublime Text and your OS, the location of the `/Lua` folder may vary. | ||
|
|
||
| Required. The output directory where the code completion file(s) will be created. | ||
|
|
||
| * `--pathFormat` | ||
| #### XML | ||
|
|
||
| CreateApiDescription will print all kinds of useful warnings regarding possible errors in your Moai code. This option determines the paths to these code files will be displayed in messages. Valid options are: | ||
|
|
||
| * `Absolute` (default), e.g. `c:\dev\moai\src\moai-sim\MOAITexture.cpp`. This may get quite long, but allows you to copy-and-paste the paths to open the files. | ||
| * `Relative`, e.g. `moai-sim\MOAITexture.cpp`. This makes for less clutter, but it may become a bit tedious to manually open the files. | ||
| * `URI`, e.g. `file:///c:/dev/moai/src/moai-sim/MOAITexture.cpp`. If you redirect the output to a text file, some editors (such as [Notepad++](http://notepad-plus-plus.org/) on Windows) will display the paths as clickable links, allowing you to easily open them with a click (or, for Notepad++, a double-click). | ||
| DocExport can generate XML files containing all extracted API information. This is useful if you want to write your own tool and need the Moai API in a structured format. _Note:_ DocExport can easily be extended to support additional export formats. So if you need code completion for editor/IDE X, it might actually be easier to build that support right into DocExport (and let everybody profit from it) than to write your own tool based on the XML output. | ||
|
|
||
| ## DocLint | ||
|
|
||
| DocLint analyzes Moai's API documentation and prints useful warnings if there may be problems. This is very useful when extending Moai with your own classes and methods. It's easy to get the documentation format wrong. Doxygen won't complain but silently generate false HTML documentation. | ||
|
|
||
| DocLint finds all kinds of documentaion problems, including: | ||
| * Misspelled types | ||
| * Syntax errors in your annotations | ||
| * Missing or multiple annotations | ||
| * Logical errors, such as impossible method signatures | ||
|
|
||
| DocLint will even analyze your method implementations and warn you if a method accesses an undocumented parameter. | ||
|
|
||
| ### Running DocLint | ||
|
|
||
| DocLint supports the following command-line arguments: | ||
|
|
||
| * `-i`, `--input` The Moai base directory. | ||
| * `-u`, `--pathsAsUri` Optional. Formats file paths as URIs. Some text editors (such as [Notepad++](http://notepad-plus-plus.org/) on Windows) will display them as clickable links, allowing you to easily navigate to the problematic source files. | ||
|
|
||
| On Windows, a typical invocation will look like this: `DocLint.exe -i "D:\moai-dev"`. | ||
| If you're on something other than Windows (i.e., Linux or OS X), you can run the tool using [Mono](http://www.mono-project.com/Main_Page). There's no need to recompile. Just run `mono DocLint.exe <arguments>`. |