Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Repo info
Activity
    Gerhard Preuss
    @lipp
    $ npm install doclets -g 
$ cd your-project
$ doclets preview 8090
    actually i started developing this but suspended it for now. i'll create an "enhancement" issue
    Jan Aagaard Meier
    @janmeier
    Cool, sounds good :)
    How is the documentation generated? Does it use the default jsdoc cli, or another parser?
    Gerhard Preuss
    @lipp
    it is using the jsdoc cli package with a custom plugin which outputs the parsed data as JSON. Then from the raw JSON data the html is generated
    Jan Aagaard Meier
    @janmeier
    Ah okay :)
    I might try my luck with the jsdoc cli for now then, since most of the errors now are functions ending up in the wrong namespace (actually no namespace at all)
    https://doclets.io/janmeier/sequelize/janmaster
    Gerhard Preuss
    @lipp
    yes, this should work for you. the naming hierarchy is the same as outputed by jsdoc cli. but if not defined, namespaces are auto guessed. A symbol named foo.bar will be nested into an implicitly defined namespace "foo" if it is not existent. But I really recommend to do it explicitly as jsdoc would like to have it.
    Gerhard Preuss
    @lipp
    @genu what exactly do you mean with angular jsdoc flavor? could you provide me some link?
    Jan Aagaard Meier
    @janmeier
    @lipp Do you have any please for supporting nested arguments in another form than just lists? A lot of sequelize's methods have an options object, which has a lot of optional properties. In regular jsdoc its rendered as a nested table, whereas doclets renders everything in one list
    blob
    Which sometimes gets very long ;)
    blob
    Actually, heres a better example, with double nesting
    And here's the corresponding on doclets https://doclets.io/janmeier/sequelize/janmaster#dl-all
    Gerhard Preuss
    @lipp
    @janmeier yeah that's a difficult thingy with no obvious / ideal solution.
    the problem i see: with each nesting level you somehow indent and thus loose horizontal space, which (after some levels) get unreadable
    Jan Aagaard Meier
    @janmeier
    Yeah that's true
    Gerhard Preuss
    @lipp
    without nesting you loose readability in terms of context
    Jan Aagaard Meier
    @janmeier
    If you indent you can write hooks instead of options.hooks, which makes the line a bit shorter
    But all in all you loose space
    Gerhard Preuss
    @lipp
    maybe there is a clever way to combine both? for instance a nested (abbreviated) variant which could unfold...
    Jan Aagaard Meier
    @janmeier
    Folding would be nice :)
    Gerhard Preuss
    @lipp
    maybe you can create an issue concerning the nested parameter problem? so i'll keep it on TODO. right now there are some other things which are more urgent from my point of view.
    Jan Aagaard Meier
    @janmeier
    Only problem might be searchability
    Sure :)
    Gerhard Preuss
    @lipp
    true
    search panel is also on the list :)
    thanks for the great feedback!
    Jan Aagaard Meier
    @janmeier
    You're welcome! :)
    Currently we use a custom script to generate the docs and host them on readthedocs - But it still requires me to run that script and update the files from time to time. And a lot of people try to edit the docs directly instead of the comments
    Gerhard Preuss
    @lipp
    ok, ... i think this "keeping information twice" can be a problem
    if you have any wishes / critic on anything, don't hesitate to say so!
    if you have any plans to merge back to main repo there are two things:
    1. organization support is not implemented yet. working on it and hopefully coming within 1-2 weeks
    2) before accepting the PR (for instance containing the .doclets.yml file) the targeted repo should be added/enabled to doclets.io beforehand.
    (else doclets.io will miss the webhook)
    Jan Aagaard Meier
    @janmeier
    Definitely agreed, the two are almost always out of sync ;)
    I'll keep that in mind, thanks
    Gerhard Preuss
    @lipp
    btw: did you see the "playground" stuff?
    https://doclets.io/lipp/acme-jsdoc-example/master#dl-greet
    Jan Aagaard Meier
    @janmeier
    @lipp No i didn't, but that looks nice indeed!
    Do you know if tonic allows you to have like a default setup for all playgrounds? I'm thinking along the lines of for sequelize we'd need to setup a new instance and define some default models for all playgrounds - And i wouldn't want that setup to be visible
    Gerhard Preuss
    @lipp
    i dont think this is possible
    would be really great to have though
    maybe doclets could give you something in the doclets.yml file for reference in the jsdoc comments... 
    playgroundbases:
  - simple: ./doc/simple.js
  - advanced: ./doc/advanced.js
    Gerhard Preuss
    @lipp
    then as comment 
    /**
 *
 * @playground simple
 * var x = somestuff.from.simple.setup
 *
 */