XML documentation?

[pixtur]

My biggest hurdle of using imgui is the lack of built in documentation. I know that the end of line comments in imgui.h are all over the place and probably not always useful without a context, but it would be extremely helpful to convert a line like this...

IMGUI_API void          Dummy(const ImVec2& size);                                      // add a dummy item of given size. unlike InvisibleButton(), Dummy() won't take the mouse click or be navigable into.

into ...

///<summary>
/// add a dummy item of given size. unlike InvisibleButton(), Dummy() won't take the mouse click or be navigable into.
///</summary>
public static void Dummy(Vector2 size);

I would be very happy to contribute manual formatting of the original header file to help with this.

[mellinoe]

I would like to have this, but it's not feasible to manually add XML comments for everything. The vast majority of the code here is generated from pre-parsed JSON definitions (from https://github.com/cimgui/cimgui), so anytime they were regenerated, the comments would be lost. The best solution would be to have the Lua script pull out the comments and make them available in the JSON file. Then, I could just put them into an XML comment during the generation phase.

[pixtur]

Thank your for this answer. I'm not familiar with lua, but it appears that the script is already extracting the comments for the most part. Sadly only to strip them. Maybe I can add a feature request to cimgui.

I have been wondering if I should ask ocornut to change the documentation style of the header file into something that is machine readable. But seeing the lua script I realized that this would require a huge amount of work and probably would break many scripts in the dear imgui eco system.

[mellinoe]

I have been wondering if I should ask ocornut to change the documentation style of the header file into something that is machine readable. But seeing the lua script I realized that this would require a huge amount of work and probably would break many scripts in the dear imgui eco system.

IMO, the current style of (most) comments in imgui.h should be easily parseable. Indeed, as you noticed, the current parser already strips them out, so it's just a matter of preserving them and associating them with the appropriate function/struct. There's obviously stuff in there that will be harder to parse out (like descriptive block comments for sections), but the majority of functions have a clean, short comment at the end of their declaring line which by itself is a great improvement over what ImGui.NET has currently (nothing). Eventually parsing things like this would also be great, but are harder.

[sonoro1234]

@mellinoe @pixtur @ocornut Just pushed this https://github.com/cimgui/cimgui/tree/keep_text as an initial phase waiting for your comments

My comments

• Initial spaces and "\n" and // should be stripped
• assing comment to function only if it is in the same line (see: RenderText) (corrected now)
• Comments before an struct or enum should go to a field, but as they are json arrays of their members it cant be done in json (Lua can have mixing of array and collection in a table) there are two solutions: 1- transform structs and enum to collections, one field is comments the other is the array of its members. 2- Create a separate collection with key being struct or enum name and value the comment.

[mellinoe]

@sonoro1234 That is pretty cool! I'll be taking a closer look sometime soon.