search

backdrop / backdrop-issues

Issue tracker for Backdrop core.
144 stars 40 forks source link

Revamp doc blocks for the configuration management commands and make them easy to understand #4724

Open alanmels opened 3 years ago

alanmels commented 3 years ago

Description of the bug The code block on https://api.backdropcms.org/api/backdrop/core%21includes%21config.inc/function/config_set/1 says:

string $config_file: The name of the configuration object to retrieve. The name corresponds to an JSON configuration file. For

config(book.admin)

, the config object returned will contain the contents of book.admin.json.

However, the string $config_file expects only book.admin instead.

indigoxela commented 3 years ago

I agree, the wording of this doc block is really confusing.

But there's another issue:

config(book.admin) should be config('book.admin') instead. It's a string, not a constant.

Same here and here.

As the configuration management is one of the things that are different compared to Drupal, it's even more important that the related documentation is correct and easy to understand.

alanmels commented 3 years ago

Please pay special attention it will not work if config(book.admin) is given to $config_file. It should be exactly book.admin without config().

indigoxela commented 3 years ago

@alanmels Sure, but the whole block is confusing and contains misleading infos.

My suggestion would be to completely revamp all three doc blocks (config, config_get, config_set) to make them really useful.

alanmels commented 3 years ago

@indigoxela, sure, I totally support the idea to make the doc blocks more useful. In that case, I won't edit my PR, but wait for someone native English speaker to edit lingua of all relevant doc blocks.