Add UML diagrams

[rouson]

This PR adds UML documentation in the doc/ subdirectory, including

1. A README.md describing and depicting the diagrams.
2. A UML class diagram detailing the derived type relationships.
3. A UML class diagram documenting the developer API comprised of all public derived types, type-bound procedures, and generic interfaces, including user-defined structure constructors.

To Do (in a future PR)

Add a User API diagram depicting only the derived types, type-bound procedures, and constructors intended for use in applications.

[rouson]

@milancurcic these diagrams can be especially helpful for a high-level picture of what's in neural-fortran with some information that doesn't appear in FORD graphics (e.g., the different types of class relationships such, including type extension and aggregation/components). As one example of the utility, I naively misinterpreted base_layer as referring to the first of several layers in a deep neural network when in fact "base" refers to a class relationship rather than an internal structure in the network. Having a readily accessible UML diagram clears up such misinterpretations very quickly. A picture is worth a thousand words. :)

[rouson]

@milancurcic if you can tell me what derived types are intended to be user-facing versus which ones are strictly for internal use, then I'll contribute one more pull request with just those to describe the "user API." This too is really helpful for a quick introduction to neural-fortran for newcomers.

[rouson]

@milancurcic I would also be glad to contribute some UML sequence diagrams that would depict the expected runtime behavior of neural-fortran, including the sequence of type-bound procedure invocations in a common use case, the objects involved, and the lifetimes of those objects.

[milancurcic]

Thanks @rouson. I'd like to have diagrams like this.

What's the advantage of these diagrams over the ones generated by FORD and graphviz? I'm reluctant to add yet another developer documentation over the one we already have.

As the API will change and grow in the near future, I suggest not committing the UML sources to the repo, but merely providing a script or instruction how to generate them. Otherwise, the diagrams will quickly fall out of date.

The user API is/will be what the nf module provides. I say "will be" because I just realized that the MNIST example uses an optimizer and MNIST loaders directly from their own modules. I think it will make sense, and be convenient, to organize the public API by themes, e.g. nf_datasets, nf_optimiziers, etc. I'm not decided yet on that and open to suggestions.

It's unlikely that the users will want to fiddle with base_layer or anything that extends it. The best way to explore the API is to start from the examples and work your way down.

[rouson]

Try 2. Responding inline this time:

Thanks @rouson. I'd like to have diagrams like this.

Great!

What's the advantage of these diagrams over the ones generated by FORD and graphviz? I'm reluctant to add yet another developer documentation over the one we already have.

UML class diagrams can provide much richer information than FORD's diagrams of class relationships. FORD diagrams will show that two types are related and show the direction of the relationship (in a way that always confuses me) but nothing else about the relationship. UML class diagrams can succinctly depict whether the relationship is inheritance versus aggregation and whether it's a one-to-many versus one-to-one and the relationship line can have a custom annotation. Also, UML class diagrams can attach formal correctness constraints to the type and its procedures (preconditions, postconditions, and invariants). I generally recommend that all such constraints be enforced by a runtime assertion, which can provide useful diagnostic information whenever a constraint is violated. The corresponding assertions provide strict verification of assumptions that people often put in a comment. Comments of course have no runtime benefit.

As the API will change and grow in the near future, I suggest not committing the UML sources to the repo, but merely providing a script or instruction how to generate them. Otherwise, the diagrams will quickly fall out of date.

In case it's helpful, the diagrams aren't part of the repository. They use the GitHub file storage trick that we discussed.I think it's really helpful to have them in the README.md because I doubt most people will generate the diagrams themselves even if given instructions. I would be glad to maintain them if that's ok with you. They're super-lightweight and easy to maintain.

The user API is/will be...

I'll get started with the User API based on your response. Thanks!

[milancurcic]

I fixed the typos and removed the redundant info. I'll let you finish up the User API diagram.

[milancurcic]

@rouson, I just noticed that you wanted to do the User API UML in another PR. I agree. If this is ready from your end, let's merge it.