Why is there no formal API documentation for the Resharper SDK?

I'm new to Resharper plug-in development, but so far I've been unable to find any official API documentation. There is the written guidelines availible online, which has been very helpful.

http://confluence.jetbrains.com/display/NETCOM/ReSharper+8+Plugin+Development

But that appears to be all there is in ways of documentation.

It seems strange that a company like JetBrains that has such a great catalog of tools designed for programmers would exclude releasing detailed API documentation for the Resharper SDK?

Whiel reviewing the SDK it appears that lot of the classes have XML documentation. So why not process that XML into a HTML document and make it availible online?

5 comments
Comment actions Permalink

Good question. The simple answer is that the API is huge, and not all documented. We don't have a plugin API that is a subset of the functionality of ReSharper. Instead, if it's a public class, you can use it. But this gives us a huge surface area to cover. And not all APIs are documented so anything that is automatically produced from existing xml docs will have huge areas of content missing.

Also, API docs are not a good way to learn how to write a plugin. They are not discoverable, and generally do not provide enough detail in order to build what you need. A slightly higher level, human curated doc is much easier to follow. For example, the devguide has a page describing how to write Live Template macros. Without this page, you'd need to know where to look in the API docs, and piece together how each class interacts based on simple summary comments. I believe a page describing how to write a macro is a better choice.

That said, the devguide is also incomplete and frequently doesn't go deep enough on a topic. This is a known issue, and is something I'm tackling at the moment. I'm looking into providing more feature coverage, and more in-depth documentation, most especially involving how to access the abstract syntax trees and semantic knowledge that ReSharper builds for your solution.

If there is anything specific you need, please feel free to ask here, and I'll be available to help.

0
Comment actions Permalink

Thanks for the quick reply.

Good question. The simple answer is that the API is huge, and not all documented. We don't have a plugin API that is a subset of the functionality of ReSharper. Instead, if it's a public class, you can use it. But this gives us a huge surface area to cover. And not all APIs are documented so anything that is automatically produced from existing xml docs will have huge areas of content missing.


Agreed, and understood. Still what can we do to get this published?

  • Can the SDK be separated out to GitHub as an open source project, and allow people to make pull requests to improve the documentation.
  • Can you publish the unfinished API under a NDA that plugin developers can sign, and then provide private forums to discuss the documentation. This way JetBrains saves face by not publicly showing that it's API is not well documented, but developers still get something.
  • The SDK does ship with the XML comments compiled to XML files. It's only *one step* away from becoming a readable HTML file.

Also, API docs are not a good way to learn how to write a plugin. They are not discoverable, and generally do not provide enough detail in order to build what you need. A slightly higher level, human curated doc is much easier to follow. For example, the devguide has a page describing how to write Live Template macros. Without this page, you'd need to know where to look in the API docs, and piece together how each class interacts based on simple summary comments. I believe a page describing how to write a macro is a better choice.


Training someone how to do something and understanding the syntax/hiarchy of a library are not the samething. Let's take "write Live Template macros" as an example. A developer is reading that tutorial and comes to the section "Macro Implementations" which he's never seen before. The tutorial refers to the interface IMacroImplemention. It would be helpful to have IMacroImplementation as a link to the API documentation so that I can see the methods and signatures, and what other things are in that namespace.

I can click -> IMacroImplementation -> HotspotItems -> ILookupItem must faster then I can read a tutorial to find ILookupItem and how to use it.

If the SDK was on GitHub. I would be more then happy to update HotspotItems with documentation and make a pull request. It's no big deal to me.

If there is anything specific you need, please feel free to ask here, and I'll be available to help.


I need more coffee, a long vacation and more work to pay the bills. As for the SDK I'm still just playing around with it.

EDIT: I got very little sleep last night. Sorry if this post sounds pushy. ;)

0
Comment actions Permalink

Thanks for the feedback on this. It's really useful and I've been giving it a lot of thought.

I'm still not convinced that the xml docs would make good documentation. These are the issues I have with it:

  • You need prior knowledge in order to navigate to a useful class or interface
  • You can't browse for something without knowing the namespace (and probably assembly, too) of the class or interface that might be useful
  • Lack of coverage. The xml docs we have are patchy at best, and don't cover everything. There are over 200 assemblies in ReSharper (yikes!) and that means a HUGE number of types. That said, it would be very interesting to know what percentage of types have any documentation, but having worked for a long time in the codebase, it'll be low
  • The level of docs is rarely above a single line summary. When it's more useful than that, there's no way of highlighting that information - you've got to get lucky with that particular topic
  • It provides no indication of how classes and types interact, or about the concepts or reasoning behind a feature


Personally, I see the best benefit of the xml docs to be to provide summary information in the editor, rather than as a reference document.

Agreed, and understood. Still what can we do to get this published?

  • Can the SDK be separated out to GitHub as an open source project, and allow people to make pull requests to improve the documentation.
  • Can you publish the unfinished API under a NDA that plugin developers can sign, and then provide private forums to discuss the documentation. This way JetBrains saves face by not publicly showing that it's API is not well documented, but developers still get something.
  • The SDK does ship with the XML comments compiled to XML files. It's only *one step* away from becoming a readable HTML file.


I don't like the idea of putting the xml docs on GitHub, mainly due to keeping it in sync with the codebase. Xml docs work best when the devs keep it up to date. But we haven't adopted that practice in the dev team, and I don't see that changing (for various reasons, e.g. non-native English speakers on the team, lack of existing docs, etc). I think duplicating the xml files on GitHub would lead to a lot of extra busywork, and work that wouldn't necessarily make it back to the codebase.

However, I really do like the idea of having the devguide on GitHub. I'd love to see issues raised asking for clarification, or giving priority for what should be documented next, and even pull requests. That would be brilliant, and I'm currently spiking a restructuring and re-hosting of the devguide where this is one of the aims.

Training someone how to do something and understanding the syntax/hiarchy of a library are not the samething. Let's take "write Live Template macros" as an example. A developer is reading that tutorial and comes to the section "Macro Implementations" which he's never seen before. The tutorial refers to the interface IMacroImplemention. It would be helpful to have IMacroImplementation as a link to the API documentation so that I can see the methods and signatures, and what other things are in that namespace.

I can click -> IMacroImplementation -> HotspotItems -> ILookupItem must faster then I can read a tutorial to find ILookupItem and how to use it.


I think linking the devguide to some kind of API viewer would be really nice. I don't think the xml docs would give us enough types to provide a good browsing experience, but it would be really cool if the devguide could link to dotPeek, which would certainly give you all the context and navigation (and find usages, viewing implementation details, and even nice fuzzy searches for terms that could be useful). But I don't really know how to make this work from a webpage, short of a dotPeek plugin to help browsing.

I do agree that APIs should be called out more visibly, though, and I'm currently trying to do that in a re-structure of the devguide. I want to split the long tutorial like pages up into smaller, more easily digestible pages, which highlight the appropriate APIs more prominently. I'm really liking the clean formatting of tools such as GitBook (think GitHub markdown) for this, but I also like the style of something like FlatDoc which pulls the source snippets out of the page text and shows them on the right hand side of the page.

I'm aware that I haven't really agreed with what you've proposed :). I hope this doesn't come across as too negative. I really do value the feedback, and I'm definitely open to persuasion.

0
Comment actions Permalink

GitBook looks great. I have a website http://pro.me-the.us that I built using wordpress and a markdown editor, but it has a lot of limitation. I think I'll move my stuff to GitBook and try it out.

You know how developers often have two kinds of books. There is a book that teaches a new language, and then there is a reference book. It would be nice to start a ReSharper SDK Reference book that contains all the commonly asked questions and class usages. For example; the PSI appears to be the foundation to all plug-ins. Would like to read on that as an expanded topic.

About The Guide
---

I think the "Fundamentals" section contains somethings that aren't really fundamental to understanding the SDK. For example; dotPeek Plugins, InspectCode Plugins are not required to understand the SDK.

Here are some of my recommendations if possible for "Fundamentals";

- dotPeek as a tool should be listed in the "Tools of the Trade" section, with an explanation to use to view the SDK internals.
- Project Set-up the section - adding /ReSharper.Internal to the command line for VS is actually really important for plug-in developers. The "Go to PSI Viewer" menu option is my most used feature. This should be promoted to a heading instead of an item on a list. I missed this the first few days and it would have saved me sometime.
- The SDK sample - Can these sample projects be moved to Git hub? They need some comments and stuff.
- Deployment and Packaging. Should these be part of "Core Concepts"? You can't packaging something if you don't understand the fundamentals.
- "Architectural Overview" - all the classes under "Platform" how do you get at them? how do I get a reference to DocumentManager for example? Would really like to see this part expanded. For example,
- "3.01 Type System" - On my first read of the guide. When I hit this point I got totally lost. I think you need to first explain the ITreeNode hierarchy first. Explain that a class in the source code is seen as a IClassDeclaration by ReSharper. I would have also liked to have learned the processing-life-cycle of ReSharper from source code to IClassDeclaration first before this chapter. When I first read "Type System" my first reaction was "okay great, how do I get references to these interfaces?".
- "3.02 Creating Code Elements" - this part is great, the only problem I had was confusion. After an element is created how does it end up back in the source code file? This is explained at the top of the document, but you're explaining result before the how too part. All it needs is the source code examples to be expanded to show the new elements being inserted into ICSharpFile. That is the one thing I kept noticing in the guidelines the code examples are to short.
- "3.03 Comments" - this has better code examples. That's what I'm talking about.
- "3.04 Multi-Language PSI" - ???? what now? I've read this a couple of times and don't understand what this is. How does this impact the average plug-in developer? I can see this is about a source code having multiple langauges inside it. I think a section just for HTML/Javascript plug-ins is better because a plug-in developer targetting those will need this specialized knowledge.

That's as far as I can comment on the guide.

Can't wait for the GitBook version!

0
Comment actions Permalink

Completely agree with you on all points, which is nice to know, shows I'm on the right tracks. Thanks for the feedback!

(And yes, PSI is the core of ReSharper and the docs definitely need to reflect this)

0

Please sign in to leave a comment.