Docs: Display interfaces

[ihadeed]

Many plugins have interfaces to define an object parameter of a method

It would be nice to have these interfaces visible in the ionic-native docs to make it easier for people to learn the usage.

@tlancina

[mlynch]

Is the comment style you're using a standard, or are you doing your own thing?

[ihadeed]

Not sure what you mean @mlynch

[mlynch]

@ihadeed basically, is the whole Platforms?: iOS, Android, Windows a standard syntax that a doc tool understands, or would we need to build a doc parser (in dgeni, for example) to handle that?

[ihadeed]

@mlynch I did some modifications in the dgeni template to display the platforms parameter for methods only. The comments displayed in the image are for an interface.. they are not being parsed or displayed in docs, just there for reference.

[mlynch]

Cool, I'm trying to figure out how we might get those comments that document the actual object into a doc so people can see the params...

[ihadeed]

I had no luck finding any dgeni tutorials/docs...

[jtushar53]

hi @ihadeed
me too was looking for dgeni tutorials,
found these,
https://forum.ionicframework.com/t/how-to-generate-our-code-documentation-with-dgeni/20056
https://github.com/rangle/angular2-dgeni-starter
may be useful for you

[ihadeed]

@mlynch do you guys already have code for this in the ionic framework repo? or should I write it from scratch?

[ihadeed]

Just had a look at https://github.com/driftyco/ionic-native/blob/master/scripts/docs/typescript-package/processors/readTypeScriptModules.spec.js#L69-L132

Seems like the processor can already read interfaces. It just needs to be rendered in the template.

[ramonornela]

@ihadeed Adjust template https://github.com/driftyco/ionic-native/blob/master/scripts/docs/templates/common.template.html maybe need processor

[ihadeed]

@ramonornela seems like the typescript-package folder contains processors that can parse interfaces, but I don't see them being imported anywhere in the process of doc generation.

I will look into it more tonight and see how this could be done.

[ramonornela]

Ionic Native usage

 "dgeni": "^0.4.2",
 "dgeni-packages": "^0.10.18"

Typescript Package available in 0.12.

[ramonornela]

Problem too Ionic see LoadingController LoadingOptions.

[ramonornela]

I think that dgeni Ionic can be created a project separated and use npm as well ionic-app-scripts

[ramonornela]

@ramonornela seems like the typescript-package folder contains processors that can parse interfaces, but I don't see them being imported anywhere in the process of doc generation.

In dgeni-config register processor

[ihadeed]

@ramonornela yeah I saw that page in the framework's docs. They're typing the docs manually for the interfaces. But the interfaces are written in a different file, maybe that's why.

In our case it should be easier to automatically document them since everything is one page.

[ramonornela]

I think that @see resolve

@see {@link /docs/native/<link> <Name Link>}

[ihadeed]

Yeah you're right they're registered in dgeni-config .. https://github.com/driftyco/ionic-native/blob/master/scripts/docs/dgeni-config.js#L4

---

I just looked into the code and figured out how (almost) everything works. Looks like dgeni opens up index.ts as a module and parses it's exports. It doesn't care if there are multiple classes/interfaces in a file, they still get separate files generated.

I think this current method wouldn't work out for ionic-native since we have lots of classes that are linked together and it wouldn't make sense to have separate pages. For example, the Google Maps plugin has many classes and interfaces exported, ideally we need all of them to be documented in the same page.

I suggest changing the doc generation process for ionic native and make it loop through all the .ts files and treating each file as a module instead. Alternatively, we could "import" the docs we need semi-manually. That can work by creating a function (macro) that fetches the doc we need by name (it can get it from doc.moduleDoc.exports[<NAME HERE>] ). The second option is probably easier to achieve.