Dedicated Documentation API

[Fusezion]

I'm here makin a proposal today regarding syntax documentation and it's availability to external sources, with the introduction of the registration api in #6246, a lot of the old system have since become more builder like structures and available without too much reflection if any.

Currently one of the largest and most important factors for addons and skript alike is documentation and it's availability to the public. Currently the way majority of syntax elements handle their documentation is via annotations. This not only requires reflection to retrieve this information but also doesn't make it easily available to other sources.

About a day ago I asked the team for feedback on if skript should move it's documentation out of it's annotations and into additional methods on the SyntaxInfo class, with what I would assume as pretty positive feedback, a good portion of non team members seem to agree it's nicer and the two or so team members that did respond in more detail also seem to like the idea just changes could be made to it. You can find the link to the original message here.

Since I want to keep this conversation going, I've decided to take some advice and transfer it to a discussion as well as provide responses to the team's responses again.

---

Before we can get into the responses it's likely best we all understand what the original implementation would of been.

Initial Design

The original design for documentation was to introduce a new class maybe something along the lines of DocumentationInfo, similar to SyntaxInfo but would be extended/implemented by it. Methods here would be similar to existing areas this type of thing can be found already, an example being SkriptEventInfo and ClassInfo both of these classes already use a builder format and is easily understood by the developers.

Design wise we'd introduce existing format with some new changes that have been made more common place within the registration api this includes a singular method to add to a list, and both a collection and singleton array method, as well as a method to clear existing information.

Self clearDescription()
Self addDescription(String description)
Self addDescriptions(String... descriptions)
Self addDescriptions(Collection<String> descriptions)

While I did introduce these I also have a dislike for this style of usage, namely wording and usage, since these are generally made within a builder developers are unlikely to have a collection on hand unless it's created in some unorthodox way. And secondly the naming and usage areas for these.

A better example for the concern would be addExample and addExamples currently no documentation site supports multiple examples on upload, this applies to SkriptLang especially, by naming the methods as such this makes the developer think each call would be to supply one full example on each consecutive call

Below is how annotations made use of each new string

@Examples({
    "on jump:",
    "\tgive player stone",
    "\tif player has permission \"group.admin\":",
    "\t\top player",
})

Bellow is how the current method implementation

.addExample("on jump:")
.addExample("\tgive player stone")
.addExample("\tif player has permission \"group.admin\"")
.addExample("\t\top player")

As you might be able to guess, this doesn't feel very intuitive if we can now encourage multi line strings

.addExample("""
    on jump:
        give player stone
        if player has permission "group.admin":
            op player
""")

There's an the PR #7470 which wishes to do this exact same thing, however just like now it doesn't make any sense if the sites do not currently support multi example uploads. While support can remain changes to how the method works should likely reflect it's usage. I'm in favor of each call acting like a new example altogether since sites like SkriptHub and SkUnity have support for them and could likely add multi example support.

Initial Feedback

Below is my response to some the teams and members of the community, while I am by no means great at java or good with terminology I will try to make the most sense of each response as I can.

@TheLimeGlass
Annotations are so much easier and cleaner. You can add multiple objects into an annotation, I don't see a need for any other context because of this.

While annotations can be called "easier" and maybe "cleaner", I have to disagree on easier, cleaner can be true so long as the documentation for it doesn't spread too far or feel like cutoffs aren't occurring to prevent more than x amount of chars on one line

However, from my limited experience in messing around with annotations, they don't feel as though they should be used for documentation purposes if it's introducing some extra behavior such as @EventHandler or @Disabled it might seem easy, but when you have no knowledge on what annotations are supported or where they can be used it's not easy for people to use.

While java has a fairly easy annotation reflection api it's still reflection and is something that should be moved away from where possible.

@APickledWalrus
we might want a generic way to put on in syntax info (since docs would ideally be a separate tool / library)
you probably don't want to have to create docs implementations of SyntaxInfo, so maybe some other way to store the data (Origin even?)

While I can't make sense of most of the mentions here I'll try to the best of my ability. Yes I agree ideally it would be better to see it as a separated tool or library, however I do not see this happening anytime soon or something that can be done with current implementations. Documentation is still heavily rooted to each syntax individually and trying to separate it now would be a much larger hassle.

"generic way to put on in syntax info", I have a very hard time trying to make sense of this one especially since I've never heard anything worded this way, but I take it as something akin to SyntaxInfo#documentation() and SyntaxInfoImpl.BuilderImpl#documentation(DocumentationBuilder) in which I do believe would be a better solution than defining this on SyntaxInfo itself, this would also allow it to be easily expanded into the other two areas such as ClassInfo and Function both of which should be moved into registration api, although that's something that can be done in the future (sooner if possible)

---

I can't seem to find any other note worthy mentions besides one made by Sparky about javadocs

i don't think docs should even be in skript, that's the responsibility of documentation engines
it's also a bit tricky for it to be in code because docs should not be able to be based on context
javadocs are fine and can be for developers working in/with API

I personally have to disagree on this being done, while it might make sense for whenever he completes the new parser and/or moves syntax registration into custom skript files *if fully agreed upon by the team*, than maybe a proper system in place for things like that could be done, however I do not believe it makes sense currently to rely on that design path.

Closing Notes

As for some of the final closing notes it's just about further expansion of the registration api for documentation and usability purposes.

Documented EntryData/Validators

I was recently talking with EyeSniper about looking into adding support for entrydata return types in the syntax that uses them, and while in theory it was possible issues occurred and ended up being treated as more impossible than anything currently.

Providing some way for elements like Structures, Sections, Effects and Expressions to explicitly state their EntryValidator would be a huge boost to documentation of these classes.

Function and ClassInfo RegistrationAPI Keys/SyntaxInfos

ClassInfos and Functions should be moved/prototyped in the registration api, both of these are registered by addons and would benefit from not only have their origins known but also be accessible in easier ways for documentation purposes if possible.

An example being the above issue with entries the point we were stuck on ended up being with getting a readable name for a classinfo from a class since apparently the Classes.getExactClassName() did not seem to wanna function for him while testing it.

Functions are another thing that would benefit from having the api expanded into the registration api, an example of a similar design can be found here was a mock design of what originally lead to the documentation changes.

[sovdeeth]

Seems like an improvement to documentation and makes it easier to access. I do wonder if we can have the best of both worlds somehow and use annotations to generate the docs for the info. Might just be worse than the sum of its parts, though.