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