On Sun, Sep 23, 2018 at 7:23 PM Peter Nabbefeld <[email protected]> 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: [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 > > > >
