Am 23.09.18 um 18:17 schrieb Jan Lahoda:
[...]
I think that having a reasonable documentation was traditionally one of the
requirements for a public API modules. (I doubt csl.api went through the
API review process.)
(next sentence is meant to be sarcastic):
So, if I'm too lazy to write some documentation, I get the benefit to
never need to think about how to do some changes, as nobody will get the
chance to use it.
Okay, that's just to make clear this requirement may be misleading. And
what about the colleages - they shouldn't be able to understand the
code, either? Sufficient documentation should not be a requirement for a
public API, but for every API - otherwise the functionality should be
considered not to be integrated into NetBeans at all.
[...]
I don't see two major NetBeans releases within 6 months, currently. But,
depending on the size of some module, IMHO, two or three major releases
of NetBeans should show most weaknesses of an API to stabilize it. If a
distinct functionality does not (yet) work as expected, declare it as
such, and make this part "private" (i.e. a friend-only module only
accessible from the API to be made public). There're many well-designed
Looking at html.editor.lib (another module mentioned in this context), I
wonder if that's considered to work "as expected", or if there are parts
that should be "private". Looking at the module, I am frankly a bit lost on
where should I begin to use it. (I assume I'd add a task using parsing.api
to "text/html", and then see if the Parser.Result I get is
HtmlParsingResult, but why are there 4 more classes with ParseResult in
name?)
Concerning the html.editor.lib module there's an API to extend the HTML
syntax, e.g. adding tags used by some of the JavaScript frameworks,
which is important for me.
After thinking of this for a little, I guess the ideal approach for
changing a friend module to public API module would be if folks interested
in the given API would get together, reviewed the API, improved it as
needed (and as possible, because with 20+ friends, it may be unrealistic to
do certain changes), added documentation, etc. and proposed to make the
updated version public.
It is of course possible to simply remove the "for friends only" flag, but
that's not going to improve the API and documentation.
Jan
[...]
And, yes, all the APIs should be reviewed, as already mentioned above.
As NetBeans is located at Apache now (i.e. no double-license anymore),
IMHO everybody should be able to understand even the most internal
functionality. As a result, this can no more be used as an argument for
friend-only state. As a result, I see the only criteria being stability.
Could You probably help to document CSL and GSF? Probably by giving an
overview how to do sth. like integrating JavaScript and HTML (without
the exact details, it's not required to rewrite the modules, but enough
detail, one could do it if possible)? E.g. how to detect and instantiate
embeddings and how to process them - this is sth. I couldn't find
sufficient information for. Further, existing examples, tutorials etc.
have to be checked for how up-to-date they're. Some UML diagrams may be
needed, too, or just some examples for how to do lexing and parsing with
the following tools:
1. Write lexer and parser manually (short example, just for
demonstration, how this could be done).
2. Usage of JavaCC (with an existing grammar). JavaCC is badly
documented, so some pointers plus additional inf would be great.
3. Usage of Antlr3 (with an existing grammar).
4. Probably also usage of Antlr4.
I'll try to comment on or extend these.
Other issues are Code Folding, Error Hinting, Guarded Blocks etc. -
there's only very poor information available.
Kind regards
Peter
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
For further information about the NetBeans mailing lists, visit:
https://cwiki.apache.org/confluence/display/NETBEANS/Mailing+lists
