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
    ok. great to hear your thoughts!
    Cinezaster
    @Cinezaster
    Self hosted also means maintaining, updating, ...
    Gerhard Preuss
    @lipp
    exactly
    i think that's the beauty of all these web services
    Cinezaster
    @Cinezaster
    indeed
    I'll keep an eye on this. If I can help with something let me know.
    Gerhard Preuss
    @lipp
    do you have other features you liked to see or "pain" doing the docs yourself?
    thanks a lot!
    Eugen Istoc
    @genu
    Hi. Does dockets support angular flavor of jsDoc?
    Gerhard Preuss
    @lipp
    no yet
    Jan Aagaard Meier
    @janmeier
    Hi there
    I've been testing out using doclets for the api docs for sequelize.js - And so far its looking good :)!
    I was wondering whether it is possible to get an idea of how the docs will look locally so I don't have to commit and wait for it to be regenerated each time?
    Gerhard Preuss
    @lipp
    hi jan!
    happy you like doclets! sorry, this is not possible yet. but i'll add a tool to npm for local testing. the workflow will be something like:
    $ npm install doclets -g 
    $ cd your-project
    $ doclets preview 8090
    Gerhard Preuss
    @lipp
    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)
    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: