Offer: willing to document

[quadroli]

Hellooo 👋 I'm down to document the user facing api of Nuklear
I've noted that not all functions are documented and the documentation is split across the wiki and the website ...
Hence I would like to bring it all together to something coherent.
Hence I'd like to know what efforts are being made towards this to see where I can help or how y'all envision this should be done

[RobLoach]

Would love some help on the documentation. Two things I can think of...

1. The Wiki docs could expand https://github.com/Immediate-Mode-UI/Nuklear/wiki
2. The inline documentation could improve too, have been thinking of making a move to Doxygen for the comments

[Xeverous]

@quadroli do you have any notes already? I'm interested in nk_widget and nk_list_view_begin - these functions are not documented at all and the second one is not used in any example.

[quadroli]

I see, I'll pay close attention to those two
No, I do not have notes ready just yet

[awschult002]

I use doxygen a lot. If you want, I can give the project a quick conversion and get a PR up for some initial feedback. I think moving to something g like doxygen and having the inoine comments sync with the website would help a lot

[quadroli]

@awschult002 💯 I second that
That would be awesome, @RobLoach would love that too

[Xeverous]

I'm writing a C++ wrapper library for Nuklear. I'm also using Doxygen. If Nuklear moved to it, I could have one documentation for both libraries in one place. That would be great.

[awschult002]

i am starting on the Doxygen stuff now. but i do have some questions on how the group would like to move forward. The existing documentation structure is not exactly how doxygen expects the information to be laid out. That isn't to say that doxygen cannot handle what currently exists; but I think restructuring comments a little bit and moving a lot of the information in nuklear.h into the separate source files would be more beneficial. This, however, would require me to start moving and copying stuff into many of the other source files and could end up creating huge merge conflicts with any existing PRs.

How much change is the project willing to take on for this update? ( i personally think it is worth it). How much change/input does the group want before the initial merge/switch to doxygen? do you want everything to move over with as much change as necessary? or do you want a minimal change right now and slowly start to integrate or migrate?

[awschult002]

@quadroli @RobLoach @Xeverous
I have kicked off a doxygen PR. Please take a look.

#722

[riri]

I think more documentation on how to use the layout systems would be nice too :)

[quadroli]

Noted ✅

[riri]

Now the move to Doxygen is done on master, maybe it would be good to centralize doc in the source tree? (source files + additional markdown if needed), and then the wiki could be removed, making github.io doc the only source of truth?

[awschult002]

i am working on another PR for doxygen. This next one will be HUGE as it adds proper header blocks to all functions. I also have started migrating things to Markdown and am considering pushing those files into the docs directory. Once the PR is up. I would love extra feedback.

[awschult002]

I did a little digging about consolidating the documentation. We can absolutely consolidate. However, HEADER.md and Readme.md have very similar information, so we need to pick one.

Readme.md is the only file (to my knowledge) that github will display as a default project page. So i believe that we should migrate all of the HEADER.md content into Readme.md then update the build script to pack in Readme.md instead of header.

Thoughts? Note: this would mean that our github project page information will end up prefixed to the header file. is that okay? Also means that project file would be identical to the main page of the documentation wiki... is that okay? do we want the main wiki page to also be the project page? or do we want different content?

[awschult002]

once PR #737 gets merged in. I will start my PR that includes the big changes to the src. There should be (ideally) no code changes; only header blocks added everywhere. I expect every single PR currently out there to end up with merge conflicts once that PR gets merged in. so we might want to figure out some way of handling that. I would be willing to help filter through existing PRs to try to fix the issues, but i don't have write access to those PRs, so it would be me make more PRs to other PRs and hoping the original authors didn't abandon anything.

i don't know if there is a good way of handling this situation other than just brute forcing it.

on a related note. does anyone here know of an easy way for me to find a PR in this project, and get that PR over to my personal fork? There are going to be situations where I would want to help fix a conflict in some one elses PR, but since that PR is setup for This project and not mine, I have to do some weird funny business where I try to branch or clone or add remotes to others forks and checkout and initiate merges on my own; then figure out how to PR back to them. idk it is kind of a mess and I am hoping someone here might know of a cleaner solution. Any advise would be appreciated.

[Xeverous]

i am working on another PR for doxygen. This next one will be HUGE as it adds proper header blocks to all functions. I also have started migrating things to Markdown and am considering pushing those files into the docs directory. Once the PR is up. I would love extra feedback.

I'm going to open my C++ nuklear wrapper library soon. It also uses Doxygen, so I will try to build both together and see if there is anything specific I need for Doxygen settings.