Move documentation inline with Doxygen

[RobertLemmens]

I've noticed that documentation is somewhat lacking. Stuff is hard to find, splintered around or simply not documented. I also notice (from other issues) that more people acknowledge this and are willing and working on it, which is nice! I have the following proposal(s):

1. Remove https://immediate-mode-ui.github.io/Nuklear/doc/index.html
2. move all documentation effor to github wiki
3. improve documentation needed for beginners
   • A take me by the hand 'Getting Started' page
   • quick links to 'Examples' and 'Demo's' and 'Component documentation'
4. document ALL components.
   • many components arent even in the component list yet. You have to scavenge through code to find out whats available.

This is motivated by a couple of reasons:

1. https://immediate-mode-ui.github.io/Nuklear/doc/index.html is somewhat unfriendly to use and seems lacking, not up to date. If i were new and wanted to get started i would click on the "Documentation" button on the readme page and be greeted first some paragraphs of text and then something that looks like full on api documentation (flags, constants, dependencies). I have to really try to find some getting started information. The site itself also doesn't look that inviting.
2. Removing https://immediate-mode-ui.github.io/Nuklear/doc/index.html and switching everything to github centralizes all documentation efforts. Everyone will know where to look, theres only one place. If its not here, it doesnt exist. This ofcourse improves the maintainability aswel.
3. Many open-source projects switched to full github wiki so the target audience should be familliar with the UI and how to use it, removing even more barriers 💯

Ofcourse i'll be willing to put an effort in this. but first, i'm wondering what your thoughts and idea's on this are.

-Robert

[dumblob]

This is in line with my observations. I just can't take the ownership of this effort due to lack of time.

I wonder what others think.

[RobertLemmens]

I've went ahead and created a PR with a mockup for a readme with good synergy with github wiki documentation and more emphasis in telling you what Nuklear is and where to find things. So we have something visual to talk about in this issue ☺️.

https://github.com/Immediate-Mode-UI/Nuklear/pull/395

see it here: https://github.com/RobertLemmens/Nuklear/tree/documentation

Some of the links i link to ofcourse wont work because those wiki entries are not there yet. I believe this makes things much clearer, a big part for newcommers is the lack of a "backend", thats something that deserves its own paragraph aswell but should also become clear once there are more good getting started guides.

[RobLoach]

I'd agree with a move from the /docs over to the Wiki. In terms of API documentation, I'm also in favour of more standard doc-comments style that aligns with doxygen ala...

/**
 * Returns a draw vertex command buffer iterator to iterate over the vertex draw command buffer
 *
 * @param nk_context Must point to an previously initialized `nk_context` struct at the end of a frame
 * @param buffer Must point to an previously by `nk_convert` filled out vertex draw command buffer
 *
 * @returns vertex draw command pointer pointing to the first command inside the vertex draw command buffer
 */
NK_API const struct nk_draw_command* nk__draw_begin(const struct nk_context*, const struct nk_buffer*);

[mavavilj]

+1

I'm currently struggling to understand how the bitwise comparisons of the kind

someflag & some NK_ flag, e.g. layout->flags & NK_WINDOW_ROM, are used.

Also, statements like:

NK_INBOX(i->mouse.pos.x,i->mouse.pos.y, g->slots[slot].last.x-3, g->slots[slot].last.y-3, 6, 6)

seem a bit confusing, because this seems like some sort of optimization. Why is it not checking relative to the full box, but relative to last.x and last.y? Why is it using absolute values?

Was also confused by the style:

NK_STYLE_ITEM_NINE_SLICE

since the name doesn't really reveal what it is about.

[RobLoach]

bitwise comparisions

https://en.wikipedia.org/wiki/Bitwise_operations_in_C

The example you posted would check if NK_WINDOW_ROM flag is enabled.

NK_STYLE_ITEM_NINE_SLICE

https://create.roblox.com/docs/building-and-visuals/ui/ui-9-slice-design

Overall, inline documentation could improve this.