search

melonjs / melonJS

a fresh, modern & lightweight HTML5 game engine
https://melonjs.org
MIT License
5.89k stars 646 forks source link

Upgrade the documentation processor to last JSDoc 3 version #66

Closed melonjs closed 11 years ago

melonjs commented 12 years ago

from : http://code.google.com/p/jsdoc-toolkit/

to : https://github.com/jsdoc3/jsdoc

obiot commented 11 years ago

jsdoc3 documentation (for reference) http://usejsdoc.org/

obiot commented 11 years ago

@DblK

Hi, grunt is in place (see #167) together with Jsdoc3, did you make any progress on your side on the template ? On my side I just fixed a few typo/mistakes in the current source, just got jsdoc3 to generate the html content, and the big next step IS actually the template :)

DblK commented 11 years ago

I'll submit a patch when I'll finish what I'm doing now. I update the makefile and also the tools.

obiot commented 11 years ago

@DblK that's great ! note that we changed the build system to use grunt now, so :

so if you submit a patch be sure to refresh your repository first (as a pull request with the previous makefile will fail), or you can send us a zip version of the template per email (contact@melonjs.org)

parasyte commented 11 years ago

Reposting here!

Replace jsdoc with dox? https://github.com/punkave/grunt-dox

obiot commented 11 years ago

oh, I never heard about this one! what about the meta data ? my only concern so far is for all the comment to be (completely this time) rewritten :)

parasyte commented 11 years ago

I'm not sure! The only thing I know about grunt-dox is no jsdoc (no Java)!

parasyte commented 11 years ago

@obiot :warning: Last ticket on 0.9.7 milestone! :smiley:

obiot commented 11 years ago

Wow yes! And not the most easy one :)

I'll have a look at dox tonight and try to evaluate what is the short term easiest solution (compared to jsdoc) Honestly I almost got all main differences in terms of tagging (I need one night to go through all the source code and update it accordingly), the most difficult part for me being on the HTML/CSS template, since this is not at all a part where I am good st (I dont't know if you can help on that?)

By he way there is as well a markdown plugin for jsdoc, that would be great to generate "GitHub" pages for the API! But I guess it's maybe another improvements for 0.9.8 :)

parasyte commented 11 years ago

re: markdown plugin ... interesting find. It could be useful for automatically generating README.md files, but I also don't want to "clutter" the repo with automated changes.

BTW, this is the actual parser used by grunt-dox: https://github.com/visionmedia/dox It looks like it just uses jsdoc-style comments and spits out JSON. Then dox-foundation puts that JSON through the template engine (Foundation) to generate the HTML documentation. That's my understanding, anyway.

And yeah, I can help with some of the HTML/CSS part.

parasyte commented 11 years ago

Oh, digging in more. The only part of Foundation used is a template/CSS. The actual template engine is jade Docs on Github: https://github.com/visionmedia/jade

(This doesn't seem too bad, but ... have to learn yet another template language! Yay? :p)

obiot commented 11 years ago

@parasyte Sorry for the late feedback but yest to come back on your last comments I also noticed that dox does not actually generate HMTL but a single big JSON file... :(

So that's why I finally decided to update for now the current source code to make it work with jsdoc, despite of the identified issues (java runtime, etc...), and we can keep looking for a better alternative without blocking the current release "just" for that.

What do you think about the current documentation state ? Shall we keep improving the documentation for this release, or do we stop here (it's 95% like the old one) ? As well I really would not say no if you would mind giving a look at the CSS file (jsdoc-template/melonjs/static/styles/jsdoc-default) and/or the layout file (jsdoc-template/melonjs/tmpl/layout.tmpl) to make it look a bit nicer ..... :)

Bonus one, I really like the viewport example you put in your blog entry, and I was wondering if we could actually add it in the documenation, to explain what is the viewport and the different between screen & world coordinates)

parasyte commented 11 years ago

Strange. grunt-dox has all the pieces to output HTML (I just looked through the code, I haven't tried it yet). But we can put it on the back burner for consideration in another ticket!

I'll have to just try it out so I can give some feedback. :)

Also yes; please use the viewport coordinates image if you wish! I actually used a screenshot from a classic NES game to make it (Adventure Island by Hudsonsoft). Not sure about copyright implications on this -- in the US it should be fine for "Fair Use" exemption, but I'm not a lawyer!

obiot commented 11 years ago

well I guess I'd better redo one using Alex4 for example, just to be sure (and furhtermore it's really not complicated to do :)

obiot commented 11 years ago

Hi!, after an awfully long journey (15h+8h flight), I'm finally back at home :) I have a few changes to commit ( including one for 0.9.8 ), but nothing on the documentation... If you have one hour to lose next week would you look at the CSS to see if there is any way to beautify it a bit more?

Else I'm in holiday next week (but just one week!), and won't have my laptop, only my iPad! So release right after I'm back :)

parasyte commented 11 years ago

Just tried it for the first time! And oh dear...

Everything else I've seen so far looks good ... HTML and images in descriptions works, optional arguments are properly displaying as optional, ...

This is weird though: https://github.com/melonjs/melonJS/blob/master/src/renderable/base.js#L16 All args for new me.Renderable are missing names! And some similar missing arg names in the TextureAtlas class.

obiot commented 11 years ago

ahah, and this already very good compared to the first output ! (you cannot imagine how much things were screwed up).

Anyway, although there is some major quality regression this time, i propose to publish the whole package when I come back next week. I'm not myself really satisfied with the current output, but I don't want to block the release just for that (and furthermore it can now easily be modified, like the tutorial, by committing changes to the github branch).

My god, I actually hate jsdoc, and this things is taking too many times to setup :p

parasyte commented 11 years ago

@obiot Agreed. And I propose fixing the docs can be done after release, since the remaining issues are very minor. It's actually usable as it is now.

That said, I've already made some changes for it to fix a couple of the items listed!

parasyte commented 11 years ago

@obiot Done with documentation for now! It's pretty. :smile:

obiot commented 11 years ago

@parasyte

honestly, you did an amazing job, and I'm not sure I would have been (technically) able to do the same :) And, I just saw your blog entry, and sorry you spent your days on it :( so double-triple-multiple thank you !

last item now is the tutorial !!! (I'm on it currently), the last big changes I made was to use the boilerplate I previously defined (https://github.com/melonjs/boilerplate), and adapt all examples to it, It still need a few updates on the html itself and we are done too !

parasyte commented 11 years ago

@obiot I'm closing this one! With the last commit, I think documentation is very close to complete (not 100%, but almost there!) We can always make minor changes later.