BYONDDoc

ID:29324
 
Apr 8 2007, 3:19 pm
I'm doing a fair few CS subjects at Uni, which is only appropriate, because I'm doing a software engineering degree. Most of my CS subjects to date use Java as their language of choice (With two exceptions - Computer Systems uses DLX assembly, and Numerical Methods uses MATLAB).

Now, I'm not Java's biggest fan. In fact, I'm on the Crispy side - Java is slow, crufty, and the Java Way encourages the proliferation of objects.

But there is one thing I think is quite nice about Java, and something that should be ported to BYOND - specifically, the Javadoc tool. There's a variant available in some other languages - Python, for example, has a similar utility called Pythondoc.

I want BYONDdoc.

What should BYONDdoc do? It should read through DM source, and construct the object tree, including variables, procs, and verbs. While doing this, it should search for special comments that indicate what follows is documentation for the below type, proc, verb, or variable, and store this information in the tree.

Finally, it should generate a (or a series of) HTML pages summarising the object tree with the documentation included.

For example:

mob
    //@type - Type used for all basic 'creatures' in the game
    creature
        var
            //@var - The current health of the creature
            health
            //@var - The maximum health of the creature
            maxhealth


That would generate a HTML file that would contain this information:

creature
Path: /mob/creature

Type used for all basic 'creatures' in the game

Variables:
health - The current health of the creature
maxhealth - the maximum health of the creature

Now, this isn't a particularly useful example, because the 'documentation' comments are blindingly obvious. But this can be useful for documenting other things, and should make it a lot easier for BYOND programmers to document their libraries, and their games. I'm a frequent offender on this count - I don't think any of my libraries have decent documentation.

I know I'd use it if I had a utility like this available (Or even if, wonder of wonders, it was included in the IDE)

I'd write it myself, but I don't think I have the knowledge. I can't come up with an algorithm to parse source code for the object tree in all cases. It generally falls down at use of braces and slashes, or worst, parent_type. I could write one where you had to put everything in the comment:

//@type creature, /mob, blah blah blah

But that's a lot uglier then what I originally had in mind.

Anyone more experienced feel like making something like this?
Apr 9 2007, 7:35 pm
Sounds parsilicious!

In a bad way.

But nah, this sounds good. It'd be even more awesome if those HTML pages had links on them that allowed you to instantly go to the right line in dream maker, too (so clicking on "creature" would take you to the definition of mob/creature in the .dm files). Although I can't really see how you'd ever do that just using standard HTML.
Jun 19 2008, 9:53 am
OpenSS13 has been considering this for a little while. If you developed an Eclipse plugin for DM, this could be integrated into that IDE.

I'm thinking we're probably heading closer to Javadoc or doxygen style documentation in terms of the comment blocks themselves.
Aug 6 2008, 9:49 am
Let's be real...

You're pursuing a Software Engineering degree, but you aren't up to the task of engineering software because you 'think' you don't have the know how?

I suppose software engineering requires no research where you school at. I think you should probably stick with Physics.

If it's worth anything, I think you could do it if you put your mind to it.
Aug 6 2008, 10:59 am
That would seem an unfair assessment of what he's suggested, Capt. What he's suggested (and it is worth acknowledging his suggestion is somewhat rare in the Industry) that he feels he does not have the experience or know-how to do it currently. This conclusion is a pleasant surprise, considering how many Software Engineers claim proficiency when it's simply not there, resulting in sub-par software.

Not to mention, considering how wide Software Engineering is, you'll come across experienced Software Engineers who know nothing about lexing/parsing, because their particular job never required it.

However, the result of the conclusion should be 'Okay, I'll go learn more about this' as opposed to 'I just can't do it', which is what most miss and I suspect what you were perhaps eluding to.
Aug 6 2008, 10:30 pm
Capt, this was posted last year, when I was in the first semester of my second year at uni.

I'd probably have somewhat of a better chance of pulling something like this off, but what you don't appreciate is that lexing is hard. I'm not sure I could lex DM source code correctly in all cases. I can certainly lex a subset - I've got a project sitting around that does.

Also, I didn't think my CSS was this ugly. <_<