ionic-team / capacitor-docgen Goto Github PK

Currently we are busy refactoring the Capacitor Google Maps plugin. One of the improvements is better documentation. The fork (WIP) can be found here: https://github.com/DutchConcepts/capacitor-google-maps/tree/next

I use docsify to generate an organized documentation website based on the markdown documentation (can be found in the ./docs folder in that fork). The API reference is generated with this plugin. This works really well, for which I commend you 👏.

The generated website (GitHub pages) can be found here.

As can be seen, the links generated by docgen are broken, because they are a <a> element instead of a markdown link.

It would be solved by changing:
<code><a href="#foobar">FooBar</a></code>
to
<code>[FooBar](#foobar)</code>

The docsify team said the following:

You need generate markdown syntax. Such as

[MyClass](#MyClass)

It will not be compiled if it is HTML.

Therefore I hope it can be solved in this plugin. As far as I can see now, I don't think this change does have any drawbacks, so it would make sense to implement it like this. But please do share your opinion about this.

When docs are generated for void functions, this is what appears:

The Returns line should just be removed for void functions

I have the problem that external APIs that are NOT imported in the definitions.ts file are still part of the output of the generator.

Here you can find an example: capawesome-team/capacitor-firebase#430

I'm using version 0.2.1 of the generator.

We don't need to pull in the Date interface and all its methods

https://capacitorjs.com/docs/v3/apis/local-notifications#date

Hello,

I created a new capacitor plugin: https://github.com/paystory-de/capacitor-headwind-mdm
And whenever I run this docgen command it generates a wonderful README.md - except the returns.
Its always:

isConnected() => any

And

Returns: any

Any ideas? 😉

The generated value in reference types always has the prefix @capacitor. However, community plugins have a different scope or no scope at all.

Example (see https://github.com/robingenz/capacitor-firebase/blob/main/packages/authentication/README.md#examples):

/// <reference types="@capacitor/firebase-authentication" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    FirebaseAuthentication: {
      skipNativeAuth: false,
      providers: ["apple.com", "google.com"],
    },
  },
};

export default config;

/// <reference types="@capacitor/firebase-authentication" /> should be /// <reference types="@capacitor-firebase/authentication" />.

@capacitor/geolocation

https://capacitorjs.com/docs/apis/geolocation#ios

We need to add this manually to the info.plist file. I hope you'll add this to the Capacitor doc:

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>$(PRODUCT_NAME) needs Location access for "some reason"!</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>$(PRODUCT_NAME) needs Location access for "some reason"!</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>$(PRODUCT_NAME) needs Location access for "some reason"!</string>

Right now, it does not support types called from other files.
Like: https://github.com/capacitor-community/admob/blob/feat/v3/src/definitions.ts

I believe this will help in the refactoring of many of the plugins once it is supported.

schedule() and Schedule generate the same URL fragment: #schedule

https://capacitorjs.com/docs/v3/apis/local-notifications#schedule

interfaces and enums are supported, but types are not. In the following link, it is not possible to know what ScreenReaderStateChangeListener is: https://capacitorjs.com/docs/v3/apis/screen-reader#addlistener

Hi,
thank you very much for this helpful generator.
I have the following problem since version 0.1.1:
APIs of external dependencies are included, which are not available via the plugin API (definitions.ts).

Here you can find an example: https://github.com/robingenz/capacitor-firebase-authentication/pull/122/files

In this project I have increased the version of docgen to 0.1.1 and updated the markdown. There are now many interfaces included (partly also twice), which are not available at all.

Can't link to the various addListener definitions, they all get melded together.

https://capacitorjs.com/docs/v3/apis/keyboard

https://capacitorjs.com/docs/v3/apis/local-notifications#schedule

"Schedule" shouldn't be linked to the Schedule type.

source: https://github.com/ionic-team/capacitor-plugins/blob/main/local-notifications/src/definitions.ts#L47