Community
Participate
Working Groups
Provide a better way to assist user in using API. Features : - define a documentation language to express API (inspired by Luadoc, Ldoc with a support of types) - generate html documentation from this language (we will also provide a command line tool) - extract information from documentation to provide autocompletion. - better support of local autocompletion, local highlight syntax and go to definition. The objective is to provide a way for any SDK or library providers to offer a good developer experience to their users. This new architecture have some flows compared to the current one. - The outline will be less complete. - We extract no information on the API of undocumented code We will add heuristics later to partially solve these lacks. Some documentation about this reflection is available here : http://wiki.eclipse.org/Koneki/LDT/Technical_Discussions
(In reply to comment #0) I'm not sure I understand the goal. Are you suggesting that code completion, outline view, etc should be driven by documentation? Wouldn't that mean that if my project has no documentation, then I lose a lot of features? > - define a documentation language to express API (inspired by Luadoc, Ldoc > with a support of types) I don't know much about those but would there be no way to extend them instead? Then if one loads a project with plain Luadoc for example, it could still provide neat features like Documentation view, Documentation hovers, extra information in code completion window, even if the project doesn't have the "extra" type information. > - extract information from documentation to provide autocompletion. > - better support of local autocompletion, local highlight syntax and go to > definition. I'm pretty sure that very good support can be achieved by proper parsing + indexing. Then the documentation extension can provide the extra "hint" of which completion is the best, if necessary.
(In reply to comment #1) > I'm not sure I understand the goal. Are you suggesting that code completion, > outline view, etc should be driven by documentation? Wouldn't that mean that if > my project has no documentation, then I lose a lot of features? It rather means you won't have "extra" features such as context-aware autocompletion, and that the outline will be a bit poorer for every undocumented code. FWIW there will be autocompletion for local variables, which is not the case at the moment.
(In reply to comment #1) > I don't know much about those but would there be no way to extend them instead? > Then if one loads a project with plain Luadoc for example, it could still > provide neat features like Documentation view, Documentation hovers, extra > information in code completion window, even if the project doesn't have the > "extra" type information. I agree and it was one of our goals at the beginning. But for our first implementation, we will extract all the API information from the documentation, so the full compatibility is not possible (there's too much information missing) Our language is not so different from Luadoc (LDoc) and we hope than when we will have added some heuristics (extract information from code), we will be almost fully compatible. > I'm pretty sure that very good support can be achieved by proper parsing + > indexing. Then the documentation extension can provide the extra "hint" of > which completion is the best, if necessary. We have some co-workers (especially Fabien from Metalua) who tried that kind of approach, and it's not that easy. We thought that the best solution is to start with an explicit way to express the API of a module. This means that the API of any implementation of a module will be supported with minimal efforts in terms of documentation. The next step will be to try to extract/guess information from code. In the upcoming weeks, we will deliver a beta, we hope users will appreciate it (and so will you! :-))
(In reply to comment #3) > In the upcoming weeks, we will deliver a beta, we hope users will appreciate it > (and so will you! :-)) Thank you for the explanation. I understand this is the best short term solution for you. Unfortunately, I can't add that kind of documentation to my code base. I look forward to "the next step" and will try to help in that effort. On a semi-side note, I think it would be important to make sure it's possible to contribute different completion proposal like org.eclipse.jdt.ui.javaCompletionProposalComputer and org.eclipse.cdt.ui.completionProposalComputer do. I think org.eclipse.dltk.ui.scriptCompletionProposalComputer is already there for that but I haven't tested it.
Thanks for the proposition to help on the "next step", we appreciate it! :) I invite you to have a look at http://lua-list.2524044.n2.nabble.com/ANN-Koneki-LDT-smart-content-assist-available-in-beta-td7287990.html to have more info about how to test the beta version of the new documentation based content-assist mechanism. Note that this is something we have done in a branch on github [1] because we depend on new stuff in metalua and on a couple of new lua libraries that have pending CQs ; but this is still EPL. Regarding your idea to have a way to contribute different completion proposal, that makes lot of sense indeed.
The beta is great. Found one bug so far: can't use capitalized module names - not sure if it's the filename of the lua file the module is in that can't be capitalized, or the module name (I tried multiple combinations, but it won't work). Example: put this in global.lua: ------------------------------------------------------------------------------ -- The Acme Library provides generic functions for getting the RoadRunner -- @field[parent = #global] Acme#Acme Acme preloaded module Then make a "Acme.lua" with this: ------------------------------------------------------------------------------- -- The Acme table -- @module Acme ------------------------------------------------------------------------------- -- This function enables getting that pesky RoadRunner -- @function [parent=#Acme] getRoadRunner -- @param #string command -- @return roadRunner That wont' work - but if all "Acme" is replaced with "acme" (including the file "acme.lua"), it works for auto-completion/code-assist.
You are right Hadriel. I noticed this once and forgot to open the bug... This will be fixed in the official version, and I'll try to provide an updated version of the beta. Thanks for taking the time to report this!
Hi, I tried the patch and it's working better but still failing. With everything lower-case, the module name, filename containing the module, etc. works right. If I make the module-name first-letter-uppercase, then ctrl-space at least figures out the module name, but not the functions within (the ones defined in the actual file, as opposed to the field defined in the globals.lua). I've also tried combinations of making the physical filename itself upper vs. lower case in case that's affecting it, but it's not helping. (ie, given a module named "Acme", I make the Lua file for it named "Acme.lua" or "acme.lua", but neither work). BTW, for the filed definitions in globals.lua, what do each of the three "Acme" tokens here do: ------------------------------------------------------------------------------ -- The Acme Library. -- @field[parent = #global] AcmeOne#AcmeTwo AcmeThree preloaded module I assume they represent respectively (AcmeOne) a module name, (AcmeTwo) a typeref within that module, and (AcmeThree) the field's name. Right? (In my case I'm trying to keep them all the same word, like the other fields defined in globals.lua, but I'm curious)
(In reply to comment #8) > Hi, I tried the patch and it's working better but still failing. With > everything lower-case, the module name, filename containing the module, etc. > works right. If I make the module-name first-letter-uppercase, then ctrl-space > at least figures out the module name, but not the functions within (the ones > defined in the actual file, as opposed to the field defined in the > globals.lua). > I've also tried combinations of making the physical filename itself upper vs. > lower case in case that's affecting it, but it's not helping. (ie, given a > module named "Acme", I make the Lua file for it named "Acme.lua" or "acme.lua", > but neither work). It should be working now, sorry that I messed up with the piece of code dealing with the autocompletion of the module name part! > [...] > -- @field[parent = #global] AcmeOne#AcmeTwo AcmeThree preloaded module > > I assume they represent respectively (AcmeOne) a module name, (AcmeTwo) a > typeref within that module, and (AcmeThree) the field's name. Right? Yup. And as you said, it is very likely that they usually should all have the same name, even though there's no obligation whatsoever.
Yup it works! Now the fun begins for me, in converting all our API-comments to the LDT format. :) Thanks!
FYI Sharon from the Eclipse IP team is starting to review the pending CQ, so we should be able to merge the Github branch soon (hopefully for 0.8 RC1)!
The Github work has been merged (commit 58bd4ae) and is now available in latest nightly build!
