My Go on the Cerberus X Documentation

Don't go down that route. :D It is a direct path to hell :p

Kidding aside....

The source of a 3rdparty docs file is sadly not parsed. Soooo right now not usable. I would love it if it would be.
 
You know what? I am going down this route. It's less than 50 KiB of undocumented code. How hard can it be? Seriously I think most of it will be copy/paste with a little variable name tweaking here and there and commenting, and in this process I hope to understand better what's going on. Starting now. I have to prepare stuff for my personal life, so I won't be finished soon. Why I am doing this? Well because I hate myself very much =) And also, because I want this feature: I want to be able to access the "summary field" of a decl from other places too, so I can make the indices like this:
identifier | summary

(whereas now, it's just:
identifier
)

The summary is basically just the first sentence of the description (of any module, class, function...).
 
Would anybody mind if I changed the target directory (where the html files are going to be) for 3rd party modules from "html/3rd party modules/" to "html/3rdparty/"? Because I'm no big fan of paths containing spaces. Also, all links will be properly set and all files properly moved, once the docs are rebuilt.
 
Go for it.
 
I'm still working on this. Just wanted to report where I stand: I thought "why does the apidoccer use its own parser/toker when there's a 'public' one in trans?" and I *tried* to look into that so I could make use of that... But I gave up on that. I'm too old to wrap my head around code so complex. It's so depressing. I really hope Mark learns to write properly documented code in his new job.

Anyways so I what I have now is the apidoccer capable of creating a complete tree of "DocDecl" nodes. Next step is turning that structure into the tokens the pagemaker eats... So I'm looking into that code now.

BTW I don't really understand why the pagemaker and markdown are brl modules...
 
I would not bother with MakeDocs. Imho it does a good job. I thought you want to work on the docs?
 
I am still working on the docs, that's true. But for that I also need a new feature in makedocs. And I looked into makedocs... and I decided not to implement it there. Because I have absolutely no desire to work myself through that code and possibly mess something up. You know, "never touch a running system" they say, and thus I don't touch makedocs - I'm rewriting it ;) Once I'm done, I'll show it here and let you all decide whether I did a good job or went too far/in the wrong direction/nuts.

TLDR: Makedoc does a good job. I want it to do an even better job. I don't bother with makedocs.
 
Could you tell us, what features you want to implement? Maybe a discussion about useful features could be helpful to sort out, what is worth the effort.
If I could rewrite this stuff, I would separate the docs from the source code. Don't get me wrong, it is a great idea to get a big part of the docs by just 'commenting" your code. The problem is, that good documentation inside the code is making the code unmaintainable.
 
Oh yes, good idea! Here are some useful features I would like to implement
  • Making the "summary" field of a doc item accessible from outside, so it's possible to put that one also in long lists (like an index). That's the first missing feature I found. (That's the apidoccer that should take care of that)
  • Reading the initial value of consts so it's possible to have that in the docs too. (That's the apidoccer that should take care of that)
  • Add enum support to the doccer. (apidoccer and parser)
  • Either make the apidoccer for in-.cxs documented code not greedy but instead only index elements that are actually documented - or add somehow the possibility to explicitly not index some elements. (apidoccer)
Can you think of more? Wishes? Anything?


Also, because I looked into how to parse CX code, i found some things the trans parser handles (is valid CX code) but the doccer parser doesn't. I consider that being "bugs". Maybe this one could be sorted out be using the trans parser in the doccer... but I have an opinion 'bout that.
Now, as promised, some un-featured features:
  • The cerberusdoc module header must match the actual modpath - the check for that is only done for modules documented in-.cxs, but not for separate .cerberusdoc files. Should be same behavior for both imho.
  • The doccer parser breaks, when the initial value of a parameter is a function call.
  • The doccer parser breaks fatally, when the initial value of a parameter is a non-empty array.
  • The doccer parser breaks fatally, when function parameters are distributed over several lines - this is maybe more of a problem in in-.cxs documented code, where some people are actually happy to stay under 80 chars per line.
  • The doccer parser can't handle inferred types if it's not for int or string or float (e.g. in Field texture := Texture.WhiteTexture() )

Phil7 said:
it is a great idea to get a big part of the docs by just 'commenting" your code. The problem is, that good documentation inside the code is making the code unmaintainable.
Click to expand...
Oh I'm not planning to make a documentation FOR makedocs - my concern is, that in the 2000 lines worth of makedocs code, there are only 42 actual comments (and 14 of them were added by.....: me). Not much less unmaintainable :rolleyes: I probably could try to change that (post comment Marks code), but since I wanted to add and/or fix some bits, I felt saver to go on my own journey. I hope that is comprehensible...
 
Phil7 said:
The problem is, that good documentation inside the code is making the code unmaintainable.
Click to expand...
Mmmh, I tend to disagree. For my fantom frameworks, I went down this route. Commented everything inside the source code and having a selfmade tool spill out .cerberusdoc files. These frameworks are not small and I think they are maintainable.
 
I had a quick look into your framework and you did a really did a good job balancing the code and the docs.
When I mentioned 'good' documentation, I was thinking about really beginner friendly docs with an average of about 15 lines of description per Function/Method followed by a runnable example (I saw, you linked to an example outside the source code) . Look at the docs of PureBasic to see what I am talking about. Hope you tend to agree more with this in mind!?
I'd like to see the autogenerated docs for syntax and short description in combination with a thoroughly handcrafted doc with examples that run out of the box.
The main problem here is how to keep the docs updated if there are changes in the syntax.
 
I'm absolutely not planning in changing the existing syntax! I want to append stuff in a way, so that existing cerbesudoc code still generates the same output. :eek:


Well except there is one veeeeeeeeeHEEEEeeeery sad exception: If you look into the .cerberusdoc file of brl.requesters, the header says "# Module requesters" - it should actually be "# Module brl.requesters". So either I have to fix that .cerberusdoc file or just make "my" makedocs also ignore the modpath when parsing .cerberusdoc files... But I find that a bit ugly.

But apart from that I ran into no conflicts so far.
 
I'm still on it. Yeah it's a huge task on one hand, but on the other hand, I'm not working extremely efficiently on this. That's why it's taking me that long.

There's one thing I found, which is used in some (only a few, 2 to be exact) brl docs. Links in the form [[Modules/brl.asyncevent#UpdateAsyncEvents]] - if I analyzed everything correctly, that one would be exactly the same as [[brl.asyncevent#UpdateAsyncEvents]] with the exception that the link expects brl.asyncevent to be found in the "Modules" index. I'm not a huge fan of this form because 1. it is nowhere defined in any documentation, 2. it's unnecessary as it's the same as the other form 3. it makes link resolving more complex. I'm dropping this and will correct the few links I break by this.
 
Does anybody now what the files docs/html/decls.txt and docs/html/index.txt are used for?

edit
I guess the docs/html/index.txt is used by the IDE or IDEs to find the corresponding page to an identifier when hitting F1
 
Last edited:
Both files are used in TED regarding display of help files and messages.
 
Thanks. They seem very similar, that's what confused me. But if both are needed, both will be generated
 
Have a look:

http://www.holzchopf.ch/temp/cerberusx/docs/html/Home.html

There's a module called holzchopf.doctest that demonstrates the new feature set

Feedback welcome.

Edit
Also, all indexes (like the "Module" page) show one of the new features: Summary fields accessible from outside the actual declaration's page.

And: All example's .cxs files are missing right now.
 
This is great! IMAO this is a big step when it comes to first impressions and lerning curve for beginners.
I will dig deeper into this...
 
You must log in or register to reply here.
Back
Top Bottom