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.

[klei1984]

I'm going to open my C++ nuklear wrapper library soon.

Hello @Xeverous , is there an ETA on when do you plan to release your library?

[Xeverous]

Generally, it is ready. I wanted a bit more polish (like a pure C++ example) but it can be done later. Just need to verify it works after recent merges in Nuklear.

Regarding Doxygen, currently I run it for my code only (which means some repetitions in my documentation) but it would be very nice if I could reference Nuklear source too.

To some extent, the repetitions are unavoidable as the C++ layer sometimes changes the API somewhat (e.g. I replaced begin/end calls with constructor/destructor) and Doxygen itself is very poor when it comes to deduplicating text in documentation (e.g. you can't @copydoc and override description of a parameter).

I will comment here when the repo becomes public.

[awschult002]

oh shoot. i have totally forgotten about my PR over the holidays. I will try to prioritize this.

[Xeverous]

Repo is public: https://github.com/Xeverous/nukleus

• There is no readme, no license and no demo application yet but the project can be built as a static library (to at least verify that the C++ header is compatible with Nuklear's C header). CMake recipe supplied. Requires C++11 or newer.
• The code is documented (with some TODOs - lots of text was copied from Nuklear). You just need to build the documentation with Doxygen. Doxyfile supplied. The most comprehensive pages are "Topics", "Core", "Window" and "Context".
• My library follows and should work with any combination of Nuklear's defines. The C++ API will be selectively enabled, just like Nuklear.

My biggest concern is the compatibility of Doxygen settings. I don't plan to use Nuklear's Doxyfile (if any) but I have some settings (disabled subgrouping, disabled sorting, warning on undocumented param) that may create issues if Nuklear's documentation would be written for a different set of settings.

FYI (about my project's Doxyfile - doxygen -x Doxyfile):

# Difference with default Doxyfile 1.10.0 (ebc57c6dd303a980bd19dd74b8b61c8f3f5180ca)
PROJECT_NAME           = Nukleus
OUTPUT_DIRECTORY       = doc
BUILTIN_STL_SUPPORT    = YES
SUBGROUPING            = NO
EXTRACT_ALL            = YES
SORT_MEMBER_DOCS       = NO
WARN_NO_PARAMDOC       = YES
INPUT                  = nukleus.hpp

# don't remember what happened here
# most likely .hpp wasn't on the list
FILE_PATTERNS          = [...] (long list)

RECURSIVE              = YES
INLINE_SOURCES         = YES
HTML_DYNAMIC_SECTIONS  = YES
DISABLE_INDEX          = YES
GENERATE_TREEVIEW      = YES
FULL_SIDEBAR           = YES
GENERATE_LATEX         = NO
PREDEFINED             = NK_INCLUDE_COMMAND_USERDATA \
                         NK_INCLUDE_DEFAULT_ALLOCATOR \
                         NK_INCLUDE_DEFAULT_FONT \
                         NK_INCLUDE_FIXED_TYPES \
                         NK_INCLUDE_FONT_BAKING \
                         NK_INCLUDE_STANDARD_BOOL \
                         NK_INCLUDE_STANDARD_IO \
                         NK_INCLUDE_STANDARD_VARARGS \
                         NK_INCLUDE_VERTEX_BUFFER_OUTPUT
CLASS_GRAPH            = GRAPH