Share JSDoc configs?

[aplatti]

Hi guys! I miss working with you, but I'm still using T3 on a daily basis with my clients!! :)

I'm wondering if there is a way you can share some of your JSDoc configurations for Modules, Services, and Behaviors. I'm having a really hard time trying to setup the proper tags so that all of my modules, services, and behaviors get grouped together in the documentation.

Can you offer any guidance for tools, configs, and jsdoc tags that would allow me to have namespaces for "Modules", "Services", and "Behaviors", and then have those contain all of the classes of those types?

Thanks!
Adam

[nzakas]

I had written a JSDoc plugin that let us write our own funky JSDoc, but no longer works with the latest JSDoc. :(

You should still be able to use out-of-the-box JSDoc with T3, though. I think the best approach is to follow the advice for AMD modules, which is here: http://usejsdoc.org/howto-amd-modules.html

[ameti]

I found something strange. I am able to document the methods after the return statement ( the public ones ), but I'm not able to document the private ones (before the return inside addModule()). Am I doing something wrong?

[j3tan]

I'm fairly sure that JSDoc will only produce documentation on the public interface (which is what you are seeing). Private function documentation helps for maintenance and readability. If you have examples where JSDoc documents private closures, can you post the example here?

[ameti]

No I wasn't able to make it document my private functions, but I saw that when you make mistakes while documenting the private closure, for ex. you write @type {object} name it gives warning 'type can't have description' so It does parse that code too. Is there any solution to this, making a plugin or even changing the jsdoc code ? Because I don't want to manually write the documentation on the generated HTML files.

[ameti]

Stupid me.. I just had to add @function tag to make it work also on the private methods.

[aplatti]

FWIW, Here are the JSDoc tags I found which were closest to my desired
output:

/**

• @fileoverview Module for the form to create a new user
  * @module modules/new-user-form
  */
  Box.Application.addModule('new-user-form', function(context){
  'use strict';

  return {
  /**

  • Initilze module
  • @returns {void}
  • @memberof module:modules/new-user-form#
    */
    init: function() {
    }
    };
    });

On Tue, Feb 9, 2016 at 5:12 AM, Ardit Meti notifications@github.com wrote:

Stupid me.. I just had to add @function tag to make it work also on the
private methods.

—
Reply to this email directly or view it on GitHub
#150 (comment).

---

Adam Platti
Web User Experience Developer
adam@webuidude.com
650-793-0673

skype: adamplatti

[j3tan]

Ah nice! Thanks for the info.

[ameti]

@aplatti Hi, I have managed to change the jsdoc code and the docstrap template code to use the custom tags @behavior, @service and the default @module tag. Unfortunately I couldn't make a plugin for that.

[aplatti]

@ardit: Are you willing to share any of your code? I am also working on a
JSDoc plugin because the tags I posted last week do not separate behaviors,
modules, and services nicely in the generated documentation.

@nicholas: If you are willing to share the JSDoc plugin you wrote, I could
try making it work with the latest version of JSDoc.

On Mon, Feb 15, 2016 at 8:22 AM, Ardit Meti notifications@github.com
wrote:

@aplatti https://github.com/aplatti Hi, I have managed to change the
jsdoc code and the docstrap template code to use the custom tags @behavior
https://github.com/behavior, @service https://github.com/service and
the default @module https://github.com/module tag. Unfortunately I
couldn't make a plugin for that.

—
Reply to this email directly or view it on GitHub
#150 (comment).

---

Adam Platti
Web User Experience Developer
adam@webuidude.com
650-793-0673

skype: adamplatti

[ameti]

@aplatti I know this is the worst way how to modify the code but I didn't have much time and needed to be done quickly. I modified a couple of files at the jsdoc directories and modified the template/publish.js at the docstrap template here are the links:
https://github.com/ameti/jsdoc-modified-t3js
https://github.com/ameti/docstrap-modified-t3js

The tags are: @module, @behavior and @service
If you will be able to make that a plugin, please share.

[aplatti]

Hey guys, just wanted to keep this thread updated with what I've learned.

It looks to me like it is impossible to change the categories that JSDoc3
shows in the right sidebar to be T3 types like "Modules", "Behaviors",
"Services" without forking JSDoc. There is not even template that can be
overridden for the navigation sidebar.

So, instead of forking, I decided to use the tags I showed earlier in this
thread (@module, @memberof), and then insert some JavaScript into the pages
that parses the default JSDoc3 output and creates the headings and lists of
objects for the T3 types. I cant really share this code now, because I'm
writing it for a paying client, but basically you use the JSDoc config to
add static resources to the page, and then write a script that grabs the
"Module" list in the right sidebar, and parses it into lists of Modules,
Behaviors, and Services. Fairly trivial code.

Let me know if anyone comes up with something better.

Thanks,
Adam

On Tue, Feb 16, 2016 at 11:45 AM, Adam Platti adam@webuidude.com wrote:

@ardit: Are you willing to share any of your code? I am also working on
a JSDoc plugin because the tags I posted last week do not separate
behaviors, modules, and services nicely in the generated documentation.

@nicholas: If you are willing to share the JSDoc plugin you wrote, I
could try making it work with the latest version of JSDoc.

On Mon, Feb 15, 2016 at 8:22 AM, Ardit Meti notifications@github.com
wrote:

@aplatti https://github.com/aplatti Hi, I have managed to change the
jsdoc code and the docstrap template code to use the custom tags
@behavior https://github.com/behavior, @service
https://github.com/service and the default @module
https://github.com/module tag. Unfortunately I couldn't make a plugin
for that.

—
Reply to this email directly or view it on GitHub
#150 (comment).

---

Adam Platti
Web User Experience Developer
adam@webuidude.com
650-793-0673

skype: adamplatti

---

Adam Platti
Web User Experience Developer
adam@webuidude.com
650-793-0673

skype: adamplatti