docs(class): add _create

[cnjhb]

I did not use ldoc to generate the documentation. The Lua link for the documentation I generated is 5.1 instead of the original 5.4.

[alerque]

This makes no sense to me. This is not how you typically create an instance of something using Penlight classes. This is for overriding the default instancer. This looks more like something you'd do in the :_init() function.

Additionally the example named you used is likely to be seen as provocative or demeaning. There is no sense at all in using same names that could be interpreted as inappropriate. It just distracts from the point of the docs.

What problem are you trying to fix here? What do you need to accomplish that the documentation doesn't cover for you?

[cnjhb]

This makes no sense to me. This is not how you typically create an instance of something using Penlight classes. This is for overriding the default instancer. This looks more like something you'd do in the :_init() function.

Additionally the example named you used is likely to be seen as provocative or demeaning. There is no sense at all in using same names that could be interpreted as inappropriate. It just distracts from the point of the docs.

What problem are you trying to fix here? What do you need to accomplish that the documentation doesn't cover for you?

Sorry, my English isn't very good.
What I meant was to add _create to the documentation, because _create looks like it should be documented. Without looking at the implementation, no one would know that _create is available.

[alerque]

Without looking at the implementation, no one would know that _create is available.

This is true, but should they? Why do they need to know about it? What use case does it actually serve. It should almost never be used, it's meant to be a private function when you're doing something crazy like combining multiple class manager APIs. In those cases you probably should be looking at the implementation, not the docs.

The main issue in this PR is your example usage seems to be something that should be done via either a base class when you create define your class in the first place or via an :_init() function (both of which are documented). I'm open to having _create() documented, but we should at least give a proper explanation of when to use/not use it.

[cnjhb]

Without looking at the implementation, no one would know that _create is available.

This is true, but should they? Why do they need to know about it? What use case does it actually serve. It should almost never be used, it's meant to be a private function when you're doing something crazy like combining multiple class manager APIs. In those cases you probably should be looking at the implementation, not the docs.

The main issue in this PR is your example usage seems to be something that should be done via either a base class when you create define your class in the first place or via an :_init() function (both of which are documented). I'm open to having _create() documented, but we should at least give a proper explanation of when to use/not use it.

I believe including it in the documentation also signifies that this API is reliable. Otherwise, even if users see the implementation and know this API exists, they'll worry whether it might be removed someday in the future.