godotengine / godotengine/godot-docs
UPNP example produces error, method description needs clarification
- Dominant language
- reStructuredText
- Stars
- 5.7k
- Forks
- 3.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 25
Description
**Your Godot version:** stable, latest
**Issue description:**
>
> const PORT = 7777
> var upnp = UPNP.new()
> upnp.discover(2000, 2, "InternetGatewayDevice")
> upnp.add_port_mapping(port)
>
> To close a specific port (e.g. after you have finished using it):
>
> upnp.delete_port_mapping(port)
I would think instead it should say (port -> PORT):
```
const PORT = 7777
var upnp = UPNP.new()
upnp.discover(2000, 2, "InternetGatewayDevice")
upnp.add_port_mapping(PORT)
```
and
```
upnp.delete_port_mapping(PORT)
```
The [discover method](https://docs.godotengine.org/en/latest/classes/class_upnp.html#class-upnp-method-discover) is probably the most important here, as without it, you won't be able to do anything with UPNP. Unfortunately I find the description of the methods arguments very lacking:
> timeout is the time to wait for responses in milliseconds. ttl is the time-to-live; only touch this if you know what you're doing.
Questions I have:
**timeout**:
Why is the default 2 seconds? What is the downside of using 1 second or even 0.5? Having shorter wait time makes a big difference in how the games responsiveness feels during login. 1 second seems to work fine for me and even 0.5. But I would like to know the risks, pros and cons of changing this value.
**ttl**:
"only touch this if you know what you're doing" - this description is not helpful at all in an API documentation and at best might seems condescending to who want to learn and improve their skills.
**URL to the documentation page:**
https://docs.godotengine.org/en/latest/classes/class_upnp.html#class-upnp-method-discover
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.