My Go on the Cerberus X Documentation

Holzchopf

Moderator
Joined
Jul 31, 2017
Location
Bern, Switzerland
Well hello to everyone!

I "allowed" myself to fiddle around with the Cerberus X documentation a bit. So far, I almost exclusively molested the language reference:
  • Added all hierarchy levels to the contents (for quick access)
  • Since the Contents are now longishly, they automatically split up into convenient columns)
  • Added headings for many categories (e.g. Literals of every Type, String and Array Methods, Property Methods etc)
  • Split the chapter Programs and declarations into two
  • Updated the Strict mode chapter as it falsely stated that in strict mode, all function calls need brackets, which is not entirely true (i.e. Print "I don't cause trouble" works fine)
  • Added chapter Literals
  • Added a table of data types to the Types chapter also including the short notation for types
  • Rearranged the type sub-chapters so they all follow the rule "type description", "special functionality", "type literals"
  • Added chapter Character literals
  • Made it absolutely clear that the table with the operators is actually in order (precedence)
  • Turned the list of assignments into a more convenient table
  • Added chapter Asset import (I think it's at the right place, since this language feature overloads the functionality of the Import keyword)
  • Added chapter Custom preprocessor directives
  • Added chapter Optimisation (I strongly believe this is a language feature and therefore should be placed in the language reference)
  • Added chapter I've seen... for strange syntax sightings (I mean, what do you search for in the docs when you see <T> in a code and have absolutely no idea what this is?)
  • Added Glossary (alphabetical index of all cue words I could think of or imagine someone else trying to learn Cerberus X could think of)
  • Turned a lot of "please see chapter XYZ" into ACTUAL CLICKABLE LINKS
  • Harmonised a lot of phrasings and/or formatting

I also touched the Home page, where I added a link to the Key codes reference.

And I improved the Resource paths reference by introducing the section about what the app's data directory actually is (so far, this is only mentioned in the Trans reference).

I upload them here, so you can already have a look. Extract the files to
Cerberus/docs/cerberusdoc/Home.cerberusdoc
Cerberus/docs/cerberusdoc/Programming/Resource paths.cerberusdoc
Cerberus/docs/cerberusdoc/Programming/Language reference.cerberusdoc
and rebuild the help to see what I've done. You can back-up these files before you overwrite them if you wan't.

I will look at the other chapters too. My goal is to put an updated documentation to the git repository once we're happy with the result.
 

Attachments

MikeHart

Administrator
Joined
Jun 19, 2017
Location
Germany
Dawlane has made changes already in his version which I want to implement. Did you take them in too?
 

Holzchopf

Moderator
Joined
Jul 31, 2017
Location
Bern, Switzerland
I think the documentation's Home page should be more appealing. For a landing page, I find it a bit too chaotic =/ I'm OK with all the Modules, Classes, Interfaces, Functions... pages just being alphabetical lists. But IMHO the Home page should use a tabular layout that also describes a bit what hides behind a link (a bit like the API reference). I.E:
Target SDKs | The build targets Cerberus X can handle and how to set up the necessary tools
API reference | Overview of the functionality of Cerberus X's standard APIs
File formats | Availability of different file formats for Cerberus X targets

and so on.

Any thoughts (before I get creative)?
 

Phil7

Moderator
Joined
Jun 26, 2017
Me too. I was also thinking about improving the docs, but because I am a german native with just a little experience in Cerberus I ditched it.
I was used to PureBasic docs and Cerberus aka Monkey docs were really annoying. So here are my thoughts:
- Get rid of those endless lists of things you only find, when you allready know the name: No Modules, Classes, Interfaces, Functions,Index
- Give the apis Link an other name: Call it 'Modules', because what you find there is a List of Modules with an Explanation of usage.
- Explain the term 'Module' on the start page as 'a package of built in functionality' or similar.
- I would go for a menu containing: Getting started, Language Reference, Modules(=old apis), Tutorials and Links
- Easy to spot links to the startpage of the docs and to the cerberus website.

It would also be nice to have a possibility to highlight important lines of code in the examples to distinguish the important stuff from the necessary boilerplate code you need for a runable example.

Maybe I can help a bit by writing simple examples for missing stuff. So tell me the topic and I write a minimalistic example.

To make things easy: Could you put a updated version of the docs online, so we don't have to mess with our own lifesaving docs ;-)
 

Phil7

Moderator
Joined
Jun 26, 2017
I read through your changes and find a lot of useful stuff in it. Now I think it is definitely time to split the Language Reference into multiple pages.

For the Explanation of the functions or methods I prefer the layout like in menu 'functions' when clicking on a link there, where you find the description right under the framed syntax. The table layout just doesn't work because of the big varieties in the width of the syntax phrase.
 

Holzchopf

Moderator
Joined
Jul 31, 2017
Location
Bern, Switzerland
Good inputs, Phil! Actually the function and method descriptions for String and Array, as they are in the language reference right now, are somewhat redundant. You find lists of them in the keywords reference, when you open the String and Array pages. But there it's again just a list in which you only find what you're looking for if you're able to guess the name of the function you're looking for. To make the tables explaining the functions or methods a bit "nicer", I could imagine shorten the Method / Function column to just the method or function name (plus make it a clickable link to the corresponding docs).

So instead of
Code:
Method Length() Property | Returns the number of characters in the string.
it would just be
Code:
Length | Returns the number of characters in the string.
With "Length" being a link to to cerberus.lang/string/length

To make things easy: Could you put a updated version of the docs online, so we don't have to mess with our own lifesaving docs ;-)
Good idea! Will do that.
 

Holzchopf

Moderator
Joined
Jul 31, 2017
Location
Bern, Switzerland
Has anyone an idea what this "3rd party modules" is and how it's supposed to work? I think I could work it out by reading through (yet another un-documented source, yay) makedocs.cxs. But that's not going to happen soon.
 

Holzchopf

Moderator
Joined
Jul 31, 2017
Location
Bern, Switzerland
OK I think I found it out just by accident. Apparently we're supposed to put our module documentations in a folder called "3rdparty.cerberusdoc" instead of "cerberusdoc", so they're listed in the "3rd party modules" page. As it clearly STATES FUCKING NOWHERE IN ANY KIND OF DOCUMENTATION FOR G*DS SAKE.

Also, if you put a .png file named yourmodulename.png, that will make an icon linking to yourmodulename in the header section (so yeah, on every page).

Do we get rid of this

called "3rd party modules" documentation?

I haven't seen anyone ever using this 3rd party docs thing. Or the icon link feature - which I believe should not exist; no 3rd party module can be that important to get an always-accessible icon link.
 

Holzchopf

Moderator
Joined
Jul 31, 2017
Location
Bern, Switzerland
And who on earth wrote makedocs? I guess a guy called George since the (basically THE) makedocs class is called George. You're trying to find any helpful comments? HA! But oh guess what nice thing I found instead:
Code:
        For Local it:=Eachin indexcats
            ...
            Local index:=it.Value
            ...
            For Local it:=Eachin index
                ...
            Next
            ...
        Next
The same index variable name USED TWICE in nested loops!

Let me show how to properly comment this mayhem:
Code:
        For Local it:=Eachin indexcats
            ...
            Local index:=it.Value
            ...
            For Local it:=Eachin index ' HAPPY DEBUGGING, SUCKERS!
                ...
            Next
            ...
        Next
I am SO disappointed right now. Not because of the quality of that source... but because I'm tempted to improve stuff like this - but I don't have the time for that.
 

Pierrou

Active Member
Joined
Jul 6, 2017
pyro.png
3rd party modules = Playniax modules like Ignition X or Pyro for example. When MonkeyX and/or Playniax modules got often updated it was convenient to be able to store 3rd party modules and their docs in a special place. And to be able to access to those modules'doc by clicking an icon was convenient too.
 
Last edited:
Top Bottom