OpenMRS: OpenMRSOptions is missing in docs

[josephjclark]

OpenMRS docs currently looks like this for http.request:

But the link to OpenMRSOptions doesn't go anywhere.

For some reason the typedef has not been generated into the docs.

Is this a bug in the docs builder? Do we need to annotate the typedef with @public? (I don't think so, I think we should automatically document all typedefs. Is it because its in the http file?

Also: this type is badly named. It's not OpenMRSOptions, which is generic and meaningless. It's more like RequestOptions.

Tip: In /tools/build/src/commands/docs.ts is the code which parses the jsdocs and generates the markdown. If there's a docs builder bug, you'll see it in there.

Tip: If you run pnpm build docs from inside the openmrs package, it should build documentation into markdown for you. Check in the docs folder and you'll see if. If the OpenMRSOptions interface is defined in there, it'll be available on the docsite. That's how you know this is fixed.

[josephjclark]

@PiusKariuki here's a real challenge for you. Unrelated to you work, while looking at your PR, I noticed this bug we have in production.

Could you take a couple of hours and have a look, see if you can work out what this is? You'll be digging into an area of code that's not well documented or explained anywhere. Don't worry if it's beyond your expertise, and please track your time whether you think you can fix this or not. But If you could take a look, I'd really appreciate it.

You can ask questions here or over email or we can arrange a call this afternoon if you're totally lost.

[PiusKariuki]

Yeah I'll look into this @josephjclark. If I run into any roadblocks I'll be sure to let you know.

[PiusKariuki]

@josephjclark this works when I annotate the typedef with public

[josephjclark]

@PiusKariuki that's strange - I expect typedefs to be public by default. The only reason to declare a a typedef is to have it appear in the docsite.

In tools/build/src/commands/docs.ts, we have this:

  // Filter items which are not marked as @public
  templateData = templateData.filter(
    data => data.kind === 'typedef' || data.access === 'public'
  );

The intention of that code is to ensure that typedefs have markdown generated. I've just done a super quick search and I can see that that's not happening. Obviously we've got this problem in openMRS but I see it in cht too.

Can you spare a little more time to work out why this code isn't working? If you just run the docs builder for cht you should have a small enough dataset to debug.

If the docs.ts code is impenetrable to you don't worry, and please don't spend more than a couple of hours on this. I'm just hoping that there's some silly fix we can make to docs.ts to restore all the proper typedefs at once.

[PiusKariuki]

@josephjclark sure, I'll look into this.