Changing descriptions in .inc files

[IL0co]

I want to change how natives and forwards are presented in .inc files, please vote for the option you want to see or you can suggest your own or close this suggestion.

To see before and after, click here 44afd55

Examples:

/**
 * Description.
 * @note  Some note.
 *
 * @param Enumeration of parameters (one by parameter = one @param).
 * @error List of errors (one error = one @error).
 *
 * @return If it's not void, if it's void, then it will be empty.
 */

/**
 * Returns the array with player item ids.
 * @note  Must be closed via CloseHandle()/delete/Handle.Close().
 * 
 * @param client            Client index.
 * @error               Client is not connected/not loaded.
 *
 * @return ArrayList handle with item ids.
 */
native ArrayList Shop_GetClientItems(int client);

/**
 * Whether a player has an item.
 * 
 * @param client            Client index to check to.
 * @param item_id           Item id to check.
 * @error               Inalid client.
 * @error               Inalid ItemId.
 *
 * @return true if player has item and false otherwise.
*/
native bool Shop_IsClientHasItem(int client, ItemId item_id);

/**
 * Called when a player has been taken credits.
 * 
 * @param client            Client index who is been taken.
 * @param credits           Amount of credits a client is been taken.
 * @param by_who            See CREDITS_BY_* definitions for more info and any higher value is the admin index.
*/
forward void Shop_OnCreditsTaken_Post(int client, int credits, int by_who);

/**
 * Called when a player is being set credits to.
 *
 * @param client            Client index who is being set to.
 * @param credits           Amount of credits a client is being set to. By reference.
 * @param by_who            See CREDITS_BY_* definitions for more info and any higher value is the admin index.
 *
 * @return Plugin_Changed to apply new values. >= Plugin_Handled to block.
*/
forward Action Shop_OnCreditsSet(int client, int &credits, int by_who);

methodmap CategoryId __nullable__
{   
    // Registers new category id.
    // 
    // @param category      Category unique name.
    // @param name          Default category display name.
    // @param description       Default category description.
    // @param cat_display       Callback called on category being displayed.
    // @param cat_desc      Callback called on category's description being displayed.
    // @param cat_should        Callback called whether the category should be displayed to a player.
    // @param cat_select        Callback called when a player is trying to select the category.
    // @error           Empty unique identifier.
    // 
    // @return Category id of the category.
    public native CategoryId(const char[] category, const char[] name, const char[] description, 
                 Shop_CategoryDisplayCallback cat_display=INVALID_FUNCTION, 
                 Shop_CategoryDescriptionCallback cat_desc=INVALID_FUNCTION,
                 Shop_CategoryShouldDisplayCallback cat_should=INVALID_FUNCTION,
                 Shop_CategorySelectCallback cat_select=INVALID_FUNCTION);

    // Toggles all items of category off.
    // 
    // @param client        Client index.
    // @error           Invalid client.
    public void ToggleOff(int client) {
        Shop_ToggleClientCategoryOff(client, this);
    }
}

And also add descriptions of elements to Enum:

enum ItemType
{
    Item_None = 0,              // Cannot be used.
    Item_Finite = 1,            // Disposable, each use takes away an item.
    Item_Togglable = 2,         // Can be turned on or off.
    Item_BuyOnly = 3            // Can only be bought.
}

[R1KO]

@IL0co скинь конкретный пример "было, стало", а то не ясно что изменится. или ты просто методмапы хочешь перенести?

[IL0co]

@IL0co скинь конкретный пример "было, стало", а то не ясно что изменится. или ты просто методмапы хочешь перенести?

I want to bring the descriptions into one general view, otherwise, right now, figure out what. I also want to add @error, which will indicate ThrowNativeError

https://github.com/FD-Forks/Shop-Core/blob/892c8252ca75d9f780b440e5c0237de07b9f51e3/addons/sourcemod/scripting/include/shop/players.inc#L434-L444 https://github.com/FD-Forks/Shop-Core/blob/892c8252ca75d9f780b440e5c0237de07b9f51e3/addons/sourcemod/scripting/include/shop/players.inc#L84-L93

Make names: unique name - item_unique, category_unique; id - ItemId, CategoryId.

And also add a missing description, when I was a beginner and wrote my first plugins for the shop, looking at this API I cursed more than once 😅. https://github.com/FD-Forks/Shop-Core/blob/892c8252ca75d9f780b440e5c0237de07b9f51e3/addons/sourcemod/scripting/include/shop/register.inc#L1-L28

[IL0co]

Then why is there no @return in the inludes of the sourcemod and in the docks it normally shows that it does not return anything? Sourcemode includes https://github.com/alliedmodders/sourcemod/blob/01203a5a449b5e8a26e6f3fa6b91a3a8b9a68c07/plugins/include/sourcemod.inc#L283-L291 https://sm.alliedmods.net/new-api/sourcemod/GetPluginFilename

[CrazyHackGUT]

Потому что технически документатор, встречая @noreturn, просто удаляет @return, если он был встречен ранее. https://github.com/alliedmodders/sourcepawn/blob/47107d2a1a37a0a5478e9e7a459e3028b553a0a7/exp/docgen/generate/generate.py#L490-L495

Но докпарсер, в отличие от докгена, не видя @return и @noreturn высирает эксепшн. Где последнее происходит - сходу не найду, они его переписали в очередной раз.

[IL0co]

Я что-то не понимаю, причём тут документаторы к инклюдам шопа? Вы хотите добавить эти инклюды в онлайн справочник?

[CrazyHackGUT]

Если посмотришь историю выше, то Рико спрашивал у меня, важно ли это для генератора доки. Планов конкретно сейчас внедрять это в какой-нибудь "онлайн-справочник" нет.

[R1KO]

Если посмотришь историю выше, то Рико спрашивал у меня, важно ли это для генератора доки. Планов конкретно сейчас внедрять это в какой-нибудь "онлайн-справочник" нет.

что ты врёшь? была же какая-то дока, я не помню где ты её генерил но ты тогда еще просил меня в випке поправить инклюды чтобы докген их нормально парсил)

[IL0co]

Если посмотришь историю выше, то Рико спрашивал у меня, важно ли это для генератора доки. Планов конкретно сейчас внедрять это в какой-нибудь "онлайн-справочник" нет.

что ты врёшь? была же какая-то дока, я не помню где ты её генерил но ты тогда еще просил меня в випке поправить инклюды чтобы докген их нормально парсил)

Как по мне, проще в докгене сделать поправки на отсуствующие елементы в инклюдах, вместо того что бы каждый инклюд править, так более гибко выйдет)

[R1KO]

Если посмотришь историю выше, то Рико спрашивал у меня, важно ли это для генератора доки. Планов конкретно сейчас внедрять это в какой-нибудь "онлайн-справочник" нет.

что ты врёшь? была же какая-то дока, я не помню где ты её генерил но ты тогда еще просил меня в випке поправить инклюды чтобы докген их нормально парсил)

Как по мне, проще в докгене сделать поправки на отсуствующие елементы в инклюдах, вместо того что бы каждый инклюд править, так более гибко выйдет)

док-ген это стороння либа. Представь что ею генерят доку ко многим плагинам. И тогда проще поправить 4 инклюда в одном плагине чем в докгене

[CrazyHackGUT]

I will leave my review after I try to "push" the files to the docgen. If it works fine and recognizes everything, there will be approval.

[IL0co]

I will leave my review after I try to "push" the files to the docgen. If it works fine and recognizes everything, there will be approval.

I have doubts that the docgen will recognize the description before typedef, because I made a general description for two callbacks there.

https://github.com/FD-Forks/Shop-Core/pull/123/files#diff-a0ef43e1aa0eaee4c42b61c6ff40696722ad08cc2f286e7060e64e59380a1f32R162-R203

[CrazyHackGUT]

shop.zip docparser result.