Create all of the jsdoc Files

jasonLaster commented 10 years ago

Classes

[x] application (@jasonLaster)
[ ] approuter {stubbed version}
[ ] behavior {has a template}
[ ] collectionview {has a template} (@joshbedo)
[ ] compositeview {has a template}
[x] controller (@benfenton)
[x] itemview {has a template} (@bendman)
[x] layoutview (@jdaudier)
[ ] module {stubbed version}
[ ] object (@fabiii21)
[x] region (@jasonLaster)
[x] regionManager (@jdaudier)
[ ] view {has a template} (@jdaudier)
Functions
[x] helpers (@moimikey)
[ ] renderer
[x] bindEntityEvents (@moimikey)
[ ] domRefresh
[x] triggermethod (@moimikey)
[ ] templatecache
[ ] behaviors
[ ] callbacks

Nice docs for inspiration: https://github.com/PharkMillups/beautiful-docs

jasonLaster commented 10 years ago

Here's a good starting off point for several of the classes commit

Outlined Classes:

behavior
collectionview
compositeview
itemview
regionManager
view

Notes, this is an old first pass and some things need to tweaking

the files are in yaml and should be jsdoc
the function keys are :| and need to be : |

overall though: :money_with_wings: :money_with_wings: :money_with_wings:

moimikey commented 10 years ago

:+1:

jasonLaster commented 10 years ago

jsdoc validation would be a pretty sweat feature @jmeas, @thejameskyle jscs-jsdoc. I like the features, but the source looks pretty coupled to their own compile engine. I'd rather do this is a post compile step where we have all of the functions compiled and we could pass a validator the json metadata and source.

moimikey commented 10 years ago

would one of the validations already include YAML validation, or would that be a good necessary step as well? I can imagine that if the YAML parses but the structure is incorrect, the JSON would end up being correct; unless of course it's at that point where you validate.

jasonLaster commented 10 years ago

@moimikey - yaml validation is definitely something to consider. With the yaml i'm thinking of locking down the jsdoc spec.

examples must be an array of objects w/ keys example, name.
description must be a string

bendman commented 10 years ago

I can take on ItemView if it's still up for grabs

jamesplease commented 10 years ago

Go for it!

jasonLaster commented 10 years ago

Thanks @jdaudier for the awesome regionManager work, the docs look great!

jasonLaster commented 10 years ago

Here's a preview of what the api is going to look like on marionettejs.com

moimikey commented 10 years ago

damn gurl that looks fresh

jamesplease commented 10 years ago

@jdaudier @jasonLaster @moimikey & anyone else working on docs, please make the file names for the docs slugs.

// good names
item-view.jsdoc
bind-entity-events.jsdoc

// bad names
layoutview.jsdoc
appRouter.jsdoc

Just thought I'd mention it 'cuz I see we have an itemview.jsdoc file. It's not too big a deal, but we're working on making the filenames across the repo consistent so I figured this is a good place for us to make headway on that front.

jdaudier commented 10 years ago

You got it!

For my own reference:

Classes

application.jsdoc
app-router.jsdoc
behavior.jsdoc
collection-view.jsdoc
composite-view.jdoc
controller.jsdoc
item-view.jsdoc
layout-view.jsdoc
module.jsdoc
object.jsdoc
region.jsdoc
region-manager.jsdoc
view.jsdoc

Functions

helpers.jsdoc
renderer.jsdoc
bind-entity-events.jsdoc
dom-refresh.jsdoc
trigger-method.jsdoc
template-cache.jsdoc
behaviors.jsdoc
callbacks.jsdoc

ChetHarrison commented 10 years ago

LMK if you want some help. With 3 little kiddos my time is compressed but I think I can squeeze in a little time. Disclosure: my spelling sucks.

jdaudier commented 10 years ago

@ChetHarrison Uh... hell yes. Just let us know which "class" you wanna take. :smile:

ChetHarrison commented 10 years ago

@jdaudier I suppose

collectionview
compositeview

would make a sensible pair. So I understand the task at hand, essentially I would be taking the existing comments and replacing/augmenting them with the jsdoc format right?

jamesplease commented 10 years ago

If you want to go for those, then that's awesome. But I would wager they will be the most difficult of all of the classes. So it might be a bit of work. Just thought I'd let ya know.

ChetHarrison commented 10 years ago

Good point. 474 lines in collectionview. But I figure I could take a crack at it. What's the target due date?

jdaudier commented 10 years ago

@ChetHarrison Wanna do a quick screenhero session tomorrow and I can go over the steps with you? Sunday is doc day for me.

ChetHarrison commented 10 years ago

@jdaudier sounds like a good idea. Your NYC so I could probably do a 6AM Cali / 9AM NYC if that's ok?

ChetHarrison commented 10 years ago

The baby get's up early so I could hit Starbucks at 6. Otherwise the boys wake up and it's kid central on Sunday.

jdaudier commented 10 years ago

@ChetHarrison Don't think I'll be up that early but feel free to ping me on Gitter whenever you're free.

ChetHarrison commented 10 years ago

I figured since it is 2am NYC that would be tough! I'll catch up with you this week and thanks.

ChetHarrison commented 10 years ago

I was thinking, given the number of docs to go maybe I write a python script to get us 80% of the way there and just proofread?

samccone commented 10 years ago

what would the script do @ChetHarrison ?

jasonLaster commented 10 years ago

@ChetHarrison this commit has a lot of the standardized stuff. Not sure if we should get it in like this or do each separately. https://github.com/jasonLaster/backbone.marionette/commit/4e11f858060309d32d44b333f1a2154797b7993d

ChetHarrison commented 10 years ago

Well for starters replace // comments with /**. Then search function signatures for names and args and set them up the arg defs with default types. Probably other patterns in there that could be harvested. For a one off port it is probably stupid to create tools but if it's a push, tools are more fun.

ChetHarrison commented 10 years ago

hmm well now. I didn't refresh my Gitter feed and catch @jasonLaster comment. So with all the yaml, which I didn't anticipate, I think I definitely need a better understanding of the flow before I dig in. I assumed it was a vanilla js comment conversion to jsdoc format. Anyway, I would love to help!

jasonLaster commented 10 years ago

@ChetHarrison - we're defintely trying something a little bit different with the api than the run of the mill /** */. Here's a small write-up on the format https://github.com/marionettejs/backbone.marionette/tree/master/api. Would really appreciate the help. This will be a huge win for the marionette community.

ChetHarrison commented 10 years ago

@samccone after talking to @jdaudier I think I've got some good direction now. I think tonight I'll take a stab at a "pre-processor" script . Just to cover 80% of the easy setup. Hell, I might even throw some esprima on it and see if the entire thing could be done flawlessly parsing syntax trees. Then you could use it almost like a documentation linter (well at least for the syntax tags. You would still need to descriptions and examples.)

ChetHarrison commented 10 years ago

come to think of it. I can't be the first one to come up with that idea. I'll poke around and see what I find.

ChetHarrison commented 10 years ago

@samccone @jmeas @jasonLaster Going Node. Here is a start https://github.com/ChetHarrison/jsdoccer showing a JSON syntax tree for the following js var answer = 42

output

{
    "type": "Program",
    "body": [
        {
            "type": "VariableDeclaration",
            "declarations": [
                {
                    "type": "VariableDeclarator",
                    "id": {
                        "type": "Identifier",
                        "name": "answer"
                    },
                    "init": {
                        "type": "Literal",
                        "value": 42,
                        "raw": "42"
                    }
                }
            ],
            "kind": "var"
        }
    ]
}

Then we go from there

jasonLaster commented 10 years ago

@ChetHarrison I like where this is headed. Feel free to connect it to https://github.com/marionettejs/backbone.marionette/blob/master/tasks/jsDocFile.js or add a new grunt task that lives side-by-side. I'll be on gitter if you want to chat, pair, etc...

One more note we'll want to grab function bodies (the code for each function) so that we can show it in the api. I hope you're esprima work can help us on that front as well.

ChetHarrison commented 10 years ago

@jasonLaster kids are in bed. Let me see what I can whip up.

ChetHarrison commented 10 years ago

k so kiddos are feisty tonight but a little progress https://github.com/ChetHarrison/jsdoccer

samccone commented 10 years ago

+ :100: @ChetHarrison :)

ChetHarrison commented 10 years ago

Thanks @samccone Only managed to spend about 30 minutes at before the baby woke up and my 4 year old wanted a snug. Should be able to make some headway tonight.

ChetHarrison commented 10 years ago

And @jasonLaster I would be honored to pair with you anytime!

jasonLaster commented 10 years ago

lets make it happen. I've been meaning to get into esprima as well.

ChetHarrison commented 10 years ago

Ok so here is my plan. I'm going to make a .config 'rc' file which will map esprima syntax trees to corresponding yamlized jsdoc syntax. The node tool will read the config and any file in the input dir produce an output json file in the output dir stubbing out places like 'example' that squishyware needs to input. I'll start with a completed one as a test run and when it can replicate it I'll know the tool works. I could bypass yaml and go js -> jsdoc but having the yaml does serve a readability purpose, and frankly may be easier to generate

jasonLaster commented 10 years ago

sounds good to me

ChetHarrison commented 10 years ago

@jasonLaster I am typically available between 9am and 5pm PST M-F. I am occasionally available around 9pm+ but not reliably.

ChetHarrison commented 10 years ago

@jasonLaster ok back at it. As far as grabbing function bodies goes (I have never done this) but we should be able to "regenerate" the code from the syntax tree using the inverse operator, so to speak, a.k.a https://github.com/Constellation/escodegen

jasonLaster commented 10 years ago

@ChetHarrison - yea i've never done this either... but i was hoping to grab it with something like that

By the way, just merged this in: https://github.com/marionettejs/backbone.marionette/pull/1926.

Going back to your original plan, I think the two places where your tool will be most useful will be in linting our api and function bodies. So, comparing the written yaml (jsdoc) with the actual source e.g. do we have all of the functions and their arguments documented.

ChetHarrison commented 10 years ago

I am still trying to find the right way into the problem space in parsing the tree (top down | bottom up). I put some RX, well kinda more map/reduce, magic on the parse which seriously stabilized my sanity. So how's this for a function? getNamespacedFunctionAssignments()

check out the repo https://github.com/ChetHarrison/jsdoccer for a sweet little map/reduce Array strapon.

Anyway this appears to correctly produce the relevant data for a scenario like ...

Marionette.Application = function(options) { ... } or Marionette.getOption = function(target, optionName) { ... }

Running it on all the M modules produced this (note: empty arrays denote an absence of NamespacedFunctionAssignments).

https://gist.github.com/ChetHarrison/793330b2c11f3f5c514c

jasonLaster commented 10 years ago

Very cool. I love how clean the map/filter lookup is. With that said, I'm always amazed at how low level this AST stuff gets. Thanks for doing the heavy lifting. I think this has the ability to help us, but also help others who have large backbone apps and want to document their many view classes etc.

ChetHarrison commented 10 years ago

@jasonLaster Thanks. It is a welcome excuse to go esprima and m/r in one shot. I met the author at a JQcon in San Diego back in Feb. Check this ...

https://www.youtube.com/watch?v=FhZdAs9n6bk

ChetHarrison commented 10 years ago

BTW I am sorry my connection has been ridiculously slow. The truth is I work out of a hotel lobby so it's not like I can complain. I just got your comment about #1926. I totally agree with the linting aspect! Even in a crude format, it would be better to edit a linted doc than roll the dice on the squishyware getting it right.

samccone commented 10 years ago

No worries @ChetHarrison really appreciate the work you are doing, let us know if there is anything I can do to help!

ChetHarrison commented 10 years ago

thanks @samccone I'm going to spend some time on it today

ChetHarrison commented 10 years ago

so after comparing the completed yaml, I am going to attempt to replicate this approximate structure ...


name: <module name>

class: <class name>

extends:
    - <class name>

description: |
    <module/class description>
constructor: 
    description: |

    examples:
        -
            name: 
            example: |

properties:
    vent: |

    @type {<type>}

functions:
    name:
        description: |

        @api public
        @static
        @param {<type>} name
        @borrows <old method name> as <new method name>
        @return {<type>}
        proxy

        examples:
            -
                name: 
                example: |

events:
    -
        name: 

        description: |

        example: |

marionettejs / backbone.marionette

Create all of the jsdoc Files #1756

Classes

Functions