btk5h / skript-db

MIT License
5 stars 5 forks source link

Add Syntax Annotations #1

Closed Blueyescat closed 7 years ago

btk5h commented 7 years ago

What's the benefit of adding this? It seems like putting documentation in annotations just makes it harder to document features.

Blueyescat commented 7 years ago

How it makes harder to document features? You can update your documentation while you are editing the Java code. Maybe you are talking about you have to do in Java code with escapes etc. but that is not a real issue. Skript Documentation sites uses this so you can import your docs automatically, also TuSKe's documentation files uses this and as you know my skDocs Discord bot works with that. So you can support the community by doing that, no need to more. I think all of the addons should use documentation annotations.

btk5h commented 7 years ago

Updating documentation stored in annotations is far more tedious than updating a markdown file. Since Java does not have multiline strings, that would mean dealing with string concatenation and explicitly specifying line breaks.

I don't think third-party documentation sites have enough benefits to justify using documentation annotations. I would much rather have quality documentation available here than have bad documentation available for third-party sources.

Blueyescat commented 7 years ago

Ok i can't say more if you think like that, but i don't think dealing with annotations is that hard. I did this pull request in a few minute even i copied texts from README.md. Writing from scratch is easier. You will not have to create or edit new annotations often, pretty rare. Also editing annotations is easier.

btk5h commented 7 years ago

This should now be obsolete due to the move to SkriptDoclet in 3edaa7d10789a649b4ca9163e9c89d4ec807a04d