Ways to avoid automatically overwrite submitted documentation

[ooker777]

in commit #23, #26, #28, you say that

Ideally we merge this upstreams in the obsidian-api repository, or we find a better place to document this.

That was what I thought initially, but seeing that there is only one accepted commit in there, and thinking that the declaration file is not a good place to have detailed, well formatted-documentation anyway, I guess we should have it here.

If it will be overwritten, should we have some kind of markup so that it won't be?

[marcusolsson]

I built dts-docs to generate Markdown from a .d.ts file, and I think it could make sense to add some functionality to be able to override/append docs. Any markup added to the Markdown files will be overwritten, so the tool would need to accept the custom changes as an input when generating the docs. Though I worry that deciding on a file format to define these custom changes would likely be a complex and error-prone endeavor.

The "easiest" option would probably be to maintain a separate version of the obsidian.d.ts from which we generate the documentation. That way we can improve the docs however we'd like, without changing the generator tool. Of course, this would come with the extra burden of having to merge upstream changes, though hopefully the resulting conflicts should be easy to fix. On the flip-side, this would likely make it easier for the Obsidian team to merge the changes upstream.

[ooker777]

why not just making an object, with the api the key, the content of that api in the obsidian.d.ts is one of its value, and the content users submitting will be another value? After that it will generate the markdown files

[marcusolsson]

Could you show an example of what that would look like? Specifically, I'd be interested to know how you'd be able to document a class method this way, or for example the arguments in a constructor?

[ooker777]

Ugh, I don't know. Perhaps something like this?

classes: {
  Component: {
    load: {
      fromSource: "Load this component and its children",
      fromUser: "This method should be used in situation X, not Y" 
    } 
  } 
} 

I'm not strong at coding though. I just have done a plugin, and this is the second project I use JS

[ooker777]

@marcusolsson what do you think about this idea?

[marcusolsson]

It would require a non-trivial update to the dts-docs to support this. I don't think JSON would make for a good format to store the configuration in.

Essentially, to store user-submitted documentation outside of the obsidian.d.ts file, there are a few challenges we'd need to overcome:

• We need a way to uniquely identify the location where we'd insert the custom documentation.
• We'd need to decide how and where the custom docs is stored.
• We'd need to map the identifier to the custom Markdown.

The first one being the hardest, and would likely have several limitations. I'm afraid that building something like this would take time and effort with limited benefits.

Maintaining a "fork" of the obsidian.d.ts solves all these challenges without any development efforts. It'd also be easy for the Obsidian team to accept the changes made by the community, by simply copy-pasting into their own .ts file.