An Update on Docs

Over the course of the past month (and as an effort that will be ongoing for a while longer), we have put huge effort into improving our docs, starting with the Elements docs at docs.elementscompiler.com. In fact, I've spent most of November writing and rewriting docs topics.

While far from done, I wanted to give you a quick update on the status, to get your feedback, and also point you at some new stuff worth checking out.

Priority one for me was sorting out all broken/missing links. I'm happy to report (with a caveat) that every single link between topics is now consistent and valid. The caveat being that 116 of those are topics that have yet to be written (meaning that while they are no longer broken, internally, they are not live). Still, I think that's good progress, as we now know that these are all valid and needed.

So, what's actually done? Lots.

In the API section, Standard Types, Standard Aspects and System Functions are done, and reviewed for full coverage and completeness. Every single one of them is doc'ed, with info and samples across all four languages.

EBuild has moved into its own top section, and every single build task is covered (not all with detailed description, as that seems lower priority than many other things, but all the tasks are listed, as are their dependencies). Other areas of EBuild are covered well too, including the sections building, caching, or command-line options, as well as other details about how EBuild works. On the compiler side, all the Compiler Options and Compiler Directives have been thoroughly covered, as well.

The Language Extensions sections for C#, Swift and Java have full coverage of all the extensions we added, and their Keywords pages have also been synced up. This should really help those coming from the vendor's version of these languages to Elements to find what's new and improved in Elements' version of them.

The biggest (and still ongoing) effort has been put into the Oxygene Language section, in particular the "The Language" Spec.

Split in four main sections, two of them have been completely rewritten and verified for completeness, and these are Types (which describes all the different types the Oxygene language knows, and how to use them) and Type Members (which describes their members, from methods over properties to events or iterators). There's a treasure-trove of detail to be found there. Every single topic has been cleaned, rewritten and interlinked properly. Every syntax variation, every optional Member Modifier, is covered in completeness.

The second two sections on Oxygene are Statements and Expressions, which cover what goes into your methods. This area is my next focus point. Right now it is fleshed out (locally) so that its structure is sound and every single statement or expression type that exists in Oxygene is there, but most of the topics still need review/rework, and some ~15 of the above-mentioned missing topics fall in this area. Getting this done, and with it the entire Oxygene language spec to be solid and 100% up to date, is my next step, and hopefully should be done in the next two or three weeks.

The Oxygene Keywords page has also been completely redone, with every keyword now linking to every single use-case for it. Oxygene is a very expressive language with over 150 keywords, and this new page is one of my favorite improvements.

Of course after that, there's still more work to do. There's about 30 Language Concepts topics to be freshly written (and more might come up), and most of the existing ones need review. This is the area that focuses on general programming concepts relevant to Elements that apply to all languages (outstanding topics include e.g. Generics, the IDisposable pattern, Reflection and more). The "missing" pages here are mostly driven by links that were "needed" by the topics done for the work above. There's also a couple dozen Fire/Water topics on the list, as well as quite a few for Platforms sections.