documentation bugs ?

[tomaszdrozdz]

https://sanic.readthedocs.io/en/latest/sanic/static_files.html

chunk_size = 1  

means 1 Byte ???

If so then

chunk_size = 1024 * 1024 * 8

Shouldn't it be 8MiB ???
Not 8KB, not 8MB but just 8MiB

[ashleysommer]

Yes, I think you're right. That is a mistake in the documentation.

[tomaszdrozdz]

Also what I found in

sanic/exceptions.py:

in docstring for

def abort(status_code, message=None):
    """...
    :param message: The HTTP response body. Defaults to the messages in response.py for the given status code."""

But in code it is:

from sanic.helpers import STATUS_CODES

if message is None:
    message = STATUS_CODES.get(status_code)

[tomaszdrozdz]

And please correct me if I am wrong but:
https://sanic.readthedocs.io/en/latest/sanic/blueprints.html#blueprint-middleware

Using blueprints allows you to also register middleware globally.

But it does not seams so, and even next paragraph
https://sanic.readthedocs.io/en/latest/sanic/blueprints.html#blueprint-group-middleware
states something different:

'applied on Blueprint : bp1 Only'

---

And in code registering middleware for blueprint is done with register_named_middleware,
So this part of documentation could be corrected.

[tomaszdrozdz]

Also we could write tiny paragraph for:
register_named_middleware

[tomaszdrozdz]

And also in middlewares documentation in listeners section for listeners execution order:

The listeners are deconstructed in the reverse order of being constructed.

I think it would be more clear to describe it like that:

"before_server_start", "after_server_start" listeners are executed in order they were registered
but "before_server_stop", "after_server_stop" listeners are executed in reverse order.

[ashleysommer]

@tomaszdrozdz
As you can see there is a clear problem we are facing that code changes over time, but the documentation doesn't.
Eg:

:param message: The HTTP response body. Defaults to the messages in response.py for the given status code."""

This behavior changed when the standard HTTP response messages were refactored into "sanic.helpers" but the docstring for abort() (and possibly others) was not updated.
Similarly:

Using blueprints allows you to also register middleware globally.

This paragraph in the documentation was not updated when "named" middleware was introduced, so now blueprint middleware is only executed on the routes in that blueprint.

Of course this is a bad thing, but it is a very difficult problem to solve. When a user creates a pull request, they are only concerned about implementing a feature or fixing a bug they've found, and possibly creating a unit test for it. It is difficult for a contributor to know every place in the code that references that, or every piece of existing documentation which will now be inaccurate due to their change.

Its something we will need to continue to consider going forward.

[tomaszdrozdz]

I understand :)
I just wanted to share what I have found.
But we can work on that - I will make pull request with documentation corrections.