Documentation is lacking

[johannes1971]

Description

There is some information on the website, there are a few basic tutorials, and you can find more by hunting the web for the problems other people had, but really, a project of this scale, scope, and intended purpose should have FAR BETTER documentation. In particular, there should be full descriptions for all the following:

• All public functions.
• All (public) function arguments and return values.
• All public constants.

And with document I do not mean just repeating the name of the thing, as if that explained everything you could possibly want to know. Pretend that we don't know what a UA_TypeClassIdObjectNode is, and explain it to us. In fact, you can safely pretend we don't know any of the terminology.

There should also be documentation describing how all these things hang together (i.e. which functions do you use together, and in what order?), a bit like the tutorials already do but covering the entire thing (not just a few extremely basic examples), as well as descriptions of the lifetimes of obtained results.

To give just an example, today I learned that apparently I must call UA_Client_manuallyRenewSecureChannel to keep my connection open. Well, at least it seems to work, so that's probably right then? Now, how could I possibly have known this? The function is undocumented in the source and in the documentation, the first time I learned about it is when my customer called and complained about the client reconnecting every 8-10 minutes. Then I found bug reports by other people that were using that function. Mind you: not documentation; bug reports. So I added it, and my customer told me it's fine now. Problem solved? Or did I just get lucky?

I know that posts like this are not looked upon favorably (with expected responses along the lines of "write it yourself if you care", "you get all the documentation you paid for", or even "git gud"), but seriously, it doesn't matter how great your library is if nobody knows how to use it. I'd understand that for some beginners' first logging library, but this is used in very serious industrial environments and as such needs very serious industrial documentation, and not just a few fatally incomplete examples. Have some pride, finish the work you started!

Now, maybe I'm just completely in the wrong here, and there is some amazing documentation out there that I just haven't been able to find. If so, I'll humbly apologize. But if that's the case - why isn't that clearly pointed out on the website, then?

Background Information / Reproduction Steps

Google UA_Client_manuallyRenewSecureChannel. Realize there's nothing there that could possibly have helped you realize what it's for, or that you even need it. Wonder in despair why a project like this, that could potentially end up in things like nuclear power plants and space shuttles, is so woefully under-documented.

Used CMake options:

N/A

Checklist

Please provide the following information:

• open62541 Version (release number or git tag): 1.1.
• Other OPC UA SDKs used (client or server): none.
• Operating system: Windows 10.
• Logs (with UA_LOGLEVEL set as low as necessary) attached: N/A
• Wireshark network dump attached: N/A
• Self-contained code example attached: N/A
• Critical issue: absolutely!

[RFil]

Thanks for the great job, guys. Nevertheless, one very important part, the documentation, looks missing. Thanks to anybody who can point me in the right direction to find it.
I think that many people, me too, would be happy to pay for documentation.
Cheers,
Roberto

[paddor]

+1

I want a browsable, generated API documentation. I wanna see all the functions concerning a type/subsystem at a glance.