Documentation for API methods & properties?

Developers: Plugin & API
1

Hi,

if I have understood correctly, the plugin API is not yet in a stable state, and I understand that you are still improving it. You probably have plans about improving the documentation too.

I’m very new to this API, and the biggest issue for me as a newcomer seems to be that the TypeScript interface that you provide lacks documentation comments for most of the methods and properties it defines: obsidian-api/obsidian.d.ts at master · obsidianmd/obsidian-api · GitHub

Some methods/properties do have comments, though. In my IDE (WebStorm), I use Quick Documentation along with auto complete very often to bring up documentation comments about methods and properties whose behaviour I’m trying to figure out. When the docs are empty, it makes it quite slow for me to learn the plugin development.

I have done programming on other projects and languages for a long time and I do know that writing comments is something that you don’t always have time for, and documentation can never be perfect. The API is large and I’m not expecting it to be documented at one time over a night. So, I do not mean this post to be a complaint :slight_smile: .

I will continue my research on this API. :+1:

P.S. Sorry if this has already been discussed about. I was not lucky with a quick search.

7 Likes
2

The API could also mention Obsidian version numbers for each entity (=method/interface/property/etc), so that plugin developers know that “If I’m gonna use this feature, a user needs to have Obsidian version x.y.z or above for it to work”.

3

Hi,

It’s 2024.

It’s mindblowing to see so many plugins, yet no documentation on the API.
I tried to write a plugin to save the editor scroll state. It just didn’t seem to work.

Then I realized that there are different interfaces for readign the scroll data and setting the scroll data. One using pixels, the other lines.

There’s 0 documentation Editor - Developer Documentation

Seriously WTF, @obsidian?

editor.getScrollInfo()

    abstract getScrollInfo(): {
        /** @public */
        top: number;
        /** @public */
        left: number;
    };

this one :point_up: seems to be returning pixels
this other one :point_down: seems to be setting line numbers

abstract scrollIntoView(range: EditorRange, center?: boolean): void;
/** @public */
export interface EditorRange {
    /** @public */
    from: EditorPosition;
    /** @public */
    to: EditorPosition;
}

This other one is unclear as it appears not to be working

abstract scrollTo(x?: number | null, y?: number | null): void;
1 Like
4

I think there are so many plugin developers out there that there could be many who could voluntarily help with documenting the API. I’d like to participate myself. :+1:

If I see some API method I could write documentation for, is there a way for me to contribute? Perhaps a pull request to GitHub - obsidianmd/obsidian-api: Type definitions for the latest Obsidian API. could be one way to communicate my documentation suggestions, but AFAIK obsidian.d.ts is not a source file, i.e. editing that file via pull requests would not offer Obsidian devs an easily automated way to pull the edits to their Obsidian source code? The edits would get overwritten when obsidian.d.ts gets rebuilt? Correct me if I’m wrong about this.

So, what would be the best place / best way to contribute API documentation so that its easy to integrate to obsidian.d.ts? :slightly_smiling_face:

1 Like
5

I agree with you, the current documentation needs to be improved.

The readme of the docs repo says this:

If you want to add, remove, or expand on current content, please submit an issue before you start working on it. We will let you know if this is something that should be worked on, or not.