On Sun, Sep 23, 2018 at 7:23 PM Peter Nabbefeld <peter.nabbef...@gmx.de>
wrote:
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
Not sure what's misleading here. Traditionally, public API always had to be
documented. Friend API not so much (because it was supposed to only be used
by "friends".) So if we want to keep the traditional quality (of public
APIs), friend APIs that are converted to Public APIs should be (among
others) documented.
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.
I didn't spot this in the module (by which I don't mean it is not there),
but it sounds like a small part of the module. So, is there a particular
reason why there can't be a module, e.g. html.api or html.source,
containing reviewed APIs, rather than opening everything? As an example.
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.
Good to hear that!
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
Not sure what was the problem before - the source code was for one and a
half decade open even before Apache, anyone could have understand anything
they wanted?
friend-only state. As a result, I see the only criteria being stability.
Less sure about this - if the "stability" means "didn't change in last X
years", then e.g. html.editor.lib might pass that criterion, which by
itself would not make the API better, more maintainable or more documented.
Could You probably help to document CSL and GSF? Probably by giving an
Sorry, but probably no. There are a few reasons for that:
a) my time on this project is severely limited (we are talking about my
personal spare time only), so this task would compete with many other tasks
for my time.
b) I know very little about CSL (there may be my name on some classes in
that module - that does not mean I wrote them for this module. It typically
means I wrote them for java.editor/java.hints/java.source, and the classes
were copied including the author tag and severely modified.)
c) I was personally never convinced the CSL is the right approach - there
are "low level" APIs for implementing the language features, and CSL is
built on top of them - some consider it easier to use. I would probably be
tempted to redesign the approach.
So, I guess it would be better if someone more knowledgeable and
enthusiastic about CSL documented that.
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).
If we are talking about the "standard" APIs here (modules parsing.api,
lexer, etc.), then I'll think about that.
Jan
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: dev-unsubscr...@netbeans.incubator.apache.org
For additional commands, e-mail: dev-h...@netbeans.incubator.apache.org
For further information about the NetBeans mailing lists, visit:
https://cwiki.apache.org/confluence/display/NETBEANS/Mailing+lists
