Metadata-Version: 2.1
Name: jsdoc2json
Version: 1.0.0
Summary: A Python tool for Game Maker developers to convert JSDoc comments from GML files to JSON.
Home-page: https://github.com/Cooleure/jsdoc2json
Author: Nicolas Dejean
Author-email: nicolasdejean@laposte.net
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE.md

# jsdoc2json

`jsdoc2json` is a Python tool designed for Game Maker developers. It serves to convert JSDoc comments from Game Maker Language (GML) files into a structured JSON format. With jsdoc2json, you can easily extract and transform JSDoc comments, making it easier to analyze and integrate their code documentation into other systems or workflows.

## Table of Contents

1. [Installation](#installation)
2. [Usage](#usage)
3. [Example](#example)
4. [Project Structure](#project-structure)
5. [Contributing](#contributing)
6. [License](#license)

## Installation

Install `jsdoc2json` using the following command:

```bash
pip install jsdoc2json
```

## Usage

Usage:

```bash
python -m jsdoc2json (-file FILE_PATH | -folder FOLDER_PATH) -output OUTPUT_PATH [-debug]
```

## Example

### Single File Conversion

To convert a single GML file "Player.gml" and save it as "Player.json":

```bash
python -m jsdoc2json -file Player.gml -output ./documentation_folder
```

**Input: `Player.gml`**

```gml
/**
 * @function                   player_move
 * @description                Move the player in the given direction
 * @param {Real}  a            The speed of the player
 * @param {Real}  b            The direction of the player
 * @return {Array<Real>}       The new coordinates
 */
function player_move(speed, direction) {
    player.x += speed * cos(player.direction);
    player.y += speed * sin(player.direction);
	return [player.x, player.y];
}
```

**Output: `Player.json`**

```json
{
    "jsdoc": [
        {
            "function_tag": {
                "description": "player_move"
            },
            "description_tag": {
                "description": "Move the player in the given direction"
            },
            "param_tags": [
                {
                    "name": "a",
                    "type": "Real",
                    "description": "The speed of the player"
                },
                {
                    "name": "b",
                    "type": "Real",
                    "description": "The direction of the player"
                }
            ],
            "return_tag": {
                "type": "Array Real",
                "description": "The new coordinates"
            }
        }
    ]
}
```

### Folder Conversion

To convert all GML files within a Game Maker project "My_project":

```bash
python -m jsdoc2json -folder ./My_project -output ./documentation_folder
```

## Project Structure

The `jsdoc2json` project directory structure:

```
jsdoc2json/
â”‚
â”œâ”€â”€ main.py
â”‚
â”œâ”€â”€ modules/
â”‚   â”œâ”€â”€ jsdoc_data.py
â”‚   â”œâ”€â”€ lexical_parser.py
â”‚   â”œâ”€â”€ lexical_regex.py
â”‚   â”œâ”€â”€ lexical_tokens.py
â”‚   â””â”€â”€ syntax_parser.py
â”‚
â””â”€â”€ data/
    â”œâ”€â”€ input/
    â”‚   â”œâ”€â”€ test1.gml
    â”‚   â”œâ”€â”€ test2.gml
    â”‚   â”œâ”€â”€ Player.gml
    â”‚   â””â”€â”€ folder_containing_tests
    â”‚       â”œâ”€â”€ test3.gml
    |       â””â”€â”€ folder_containing_tests
    |           â””â”€â”€ test4.gml
    â””â”€â”€ output/
        â”œâ”€â”€ test1.json
        â”œâ”€â”€ test2.json
        â””â”€â”€ Player.json
```

## Contributing

### Reporting Bugs

If you encounter a bug, please open an issue on our [issue tracker](https://github.com/Cooleure/jsdoc2json/issues) and provide detailed information about the bug, including how to reproduce it.

## License

This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
