[PROGRAMMING] Unreal, i love new features, but can you PLEASE focus on C++ documentation?

[Jamie453]

Unreal,

Unreal 4 is a great engine, its got great features and the one i find many programmers and myself appreciating is the support for C++, which is a big feature of the Engine.

However, there is SUCH a lack of documentation for your classes, functions and general example tutorials on how to do things properly it at some points is becoming ridiculous. I would say a good 60% of functions and classes have comments such as "@todo documentation" while many of your classes provide no description of what they do what so ever. If you were to ask me the difference between the class ADetourCrowdAIController and AAIController, i would have no idea. In a similar vein, i really think that some tutorials for certain things would be so fantastic for programmers. A key example for me is how i would go about creating UI elements (in particular 3D UI elements) using C++. There is such little information on this at points its frustrating.

I have spoken to many programmers, mostly of whom are students, however some smaller indie company's and one larger studio, who have expressed a desire to use UE4 and have tested it out for there needs, but then discard it when there is no easy point of call on how to do key basic things, and in particular don't know what certain classes/functions do or how they work.

I understand that Blueprints is important to the Engine, and i can also appreciate these forums as a method of asking for C++ support, but could it not solve a lot of problems if proper documentation for your code and maybe tutorials/example on the same level you have for Blueprints was in place?

Im sure im not the first to raise this point, i love your engine, ive been using it casually since 4.3. I want to use it more, can we please just have the tools to be able to use it more efficiently?

[[Epic] Gribbs]

Howdy Jamie453,

Thanks for your feedback! Finding C++ Tutorials and Documentation pages can be a little tricky when using the Navigation Menu. Our C++ pages can be a little bit spread out. The easiest way to locate anything regarding a certain topic would be the search bar on our main Documentation Home Page.

API Documentation Pages, while being extremely helpful, can be confusing for users who are unfamiliar with C++ and/or UE4. I would use our Programming Guide, which can be found in our Navigation Bar. There are numerous Quick Starts and Tutorials for C++. You can also try our YouTube channel where we have step by step tutorials on using C++ in UE4.

As for new Videos/Pages, we have numerous requests in our database to address using C++ in UE4. I can not say when these will be tackled, but we are always working on getting out new content for requests every week.

Regarding Creating UI Elements, this YouTube Tutorial series should help out with any questions that you may have: https://docs.unrealengine.com/latest...UMG/index.html

Please let me know if you have any additional questions.

Thanks again and have a great day!
-Sean G

[kamrann]

The problem is, the Programming Guide is absolutely minimal in what it covers. This is understandable, the engine is huge after all. That's why we need a better API reference.

The fact that it might be confusing for people unfamiliar with the engine or C++ doesn't seem to be a reason not to concentrate on it. Such people have blueprints as an entry point, plus the Programming Guide for the basics. For people who've familiarized themselves with the engine, and are experienced programmers, but aren't full licensees with access to support, there is practically nothing to fall back on once you start trying to do anything other than the most trivial of tasks in C++.

Okay, so there's the engine source. I've spent an enormous amount of time going through it, and generally found out what I needed eventually. But it takes far longer than it would with a reasonably complete API reference, and I'm always left unsure of whether I've stumbled on the correct way of doing something or not.

Well anyway, I'm not expecting any major changes on this front anytime soon. At the start of the year, C++ documentation was the most voted-for item on the trello board, and various Epic staff kept saying it was in the works. I had assumed what was meant by that was a solid API reference, but I guess in the end they were just referring to the additions to the programming guide that have trickled in.

But if I can make one specific suggestion: please try to improve the automatic API docs generation process. There are actually a number of cases of very well commented header files in the code base, that for one reason or another are not picked up and don't show up in the API reference. Frequently methods themselves, or entire classes, are omitted too. If this process were improved and existing comments reformatted as needed, that alone would result in a big improvement.

[Jeff Wilson]

Hey kamrann!

I had assumed what was meant by that was a solid API reference, but I guess in the end they were just referring to the additions to the programming guide that have trickled in.

It was - and still is - meant to be both. Filling out and improving the API reference is a longer-term effort, but is underway. We have chosen to focus on the most visited pages since those are likely to be the highest value for you guys. Over time, we will expand that focus in an effort to have all classes and members fully documented.

Frequently methods themselves, or entire classes, are omitted too. If this process were improved and existing comments reformatted as needed, that alone would result in a big improvement.

If you know of specific cases where this is happening, please let us know. It's difficult to know where the issues are because of the size of the code base. If we know about them, we can more easily track down the underlying cause and fix it. We are currently analyzing the tools used in this process and coming up with a plan to make them rock solid in the future.

[kamrann]

Hi Jeff.

Filling out and improving the API reference is a longer-term effort, but is underway. Over time, we will expand that focus in an effort to have all classes and members fully documented.

That's certainly good to hear. I guess it's possible that the API reference has improved over the last year more than I realized, since if it's gradual it's hard to notice the changes. Clearly though, there is a long way to go with it.

As far as things missing, sure, I'll try to make a note anytime I notice and pass that info on to you. Just for reference, is there some division between code that should be on there and other code that is intentionally left off? Like low level editor-side code for example. Or should everything in the codebase be included ideally? Also, should this stuff be posted on the documentation subforum thread, or sent elsewhere?

Cheers.

[Jeff Wilson]

Hi Jeff.

That's certainly good to hear. I guess it's possible that the API reference has improved over the last year more than I realized, since if it's gradual it's hard to notice the changes. Clearly though, there is a long way to go with it.

As far as things missing, sure, I'll try to make a note anytime I notice and pass that info on to you. Just for reference, is there some division between code that should be on there and other code that is intentionally left off? Like low level editor-side code for example. Or should everything in the codebase be included ideally? Also, should this stuff be posted on the documentation subforum thread, or sent elsewhere?

Cheers.

Ideally, everything you can get from GitHub should be included in the API reference. You can post missing items in the Documentation Feedback forum.

Thanks!

[BrUnO XaVIeR]

I agree documentation could be a lot better. Epic needs dedicated experienced writers for that.
CryTech didn't listen and CryEngine failed the indie/hobby market.
Unity did listen and after fixing their docs, less than 2 years later they've become #1 public engine.

I see quite a frequent argument against UE4 outside this community: "-UE4 has no documentation."
Just like they say about CryEngine.

Simply generating DoxyGen files won't be enough, C++ docs must be written while assuming NO C++ experience and still be able to inform the reader successfully what that class is doing and why. With up to date code snippets for ALL of them.
While you keep adding features and have no dedicated doc team, that will never happen though.