godotengine / godotengine/godot-docs

Add Dedicated Parameter Descriptions for Functions and Methods in the Documentation

Open
#9,666 0 comments 2 reactions 0 assignees View on GitHub
area:class reference enhancement
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

**Your Godot version:**
4.2.2.stable

**Issue description:**
Hello,

I hope you're doing well. I wanted to suggest an idea that I think could really improve the Godot documentation. Right now, many functions and methods don't have detailed descriptions for their parameters, which can make it hard for developers to use them effectively. Adding these descriptions would make the documentation much more user-friendly and will reduce the learning curve for new developers.

For example, here's how the current documentation for a function looks:

```gdscript

Array[Image] get_seamless_image_3d(width: int, height: int, depth: int, invert: bool = false, skirt: float = 0.1, normalize: bool = true) const

Returns an Array of Images containing seamless 3D noise values for use with ImageTexture3D.create().

Note: With normalize set to false, the default implementation expects the noise generator to return values in the range -1.0 to 1.0.
```

And here's my suggestion for improving it:

```gdscript

Array[Image] get_seamless_image_3d(width: int, height: int, depth: int, invert: bool = false, skirt: float = 0.1, normalize: bool = true) const

- `width` (int): The width of the 3D noise texture.
- `height` (int): The height of the 3D noise texture.
- `depth` (int): The depth of the 3D noise texture.
- `invert` (bool, optional): If true, inverts the noise values. Defaults to false.
- `skirt` (float, optional): The skirt value for the noise. Defaults to 0.1.
- `normalize` (bool, optional): If true, normalizes the noise values to the range 0.0 to 1.0. Defaults to true.

Returns an Array of Images containing seamless 3D noise values for use with `ImageTexture3D.create()`.

Note: With `normalize` set to false, the default implementation expects the noise generator to return values in the range -1.0 to 1.0.
```

Here are a few reasons why this change would be of great helpl:

- While some parameter names are self-explanatory, others like 'skirt' in the example above, are not. Detailed descriptions make sure all parameters, especially those with less obvious names, are understood.

- Adding parameter descriptions to the script editor's autocomplete feature would provide developers with immediate info as they code. This means less need to constantly check the documentation or your favourite search engine.

- While some functions do explain parameters in their descriptions, it's not always consistent. Having dedicated parameter sections will make sure all parameters are documented rigorously and uniformly, which makes it easier to find specific information quickly.

- Detailed parameter documentation sets a high standard for future contributors to follow, ensuring new functions are documented thoroughly and preventing them from missing important details. This is certainly why some programming languages such as [C++](https://en.cppreference.com/w/cpp/algorithm/find_end), [Java](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Matcher.html), and [Python](https://docs.python.org/3/library/functions.html#sorted) (click on the three links for examples of documented functions) include detailed parameters descriptions. This is to me, especially important for an Open Source project such as Godot in which anyone can add functions and document them.

- Many GitHub issues arise because of the lack of parameter documentation. Adding this feature will reduce the number of issues about unclear documentation pages.

Thank you for considering this request. I am confident this feature will GREATLY improve Godot's workflow. With that, have a good day :)

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.