Attachment #139367 for bug #229272

This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.

View | Details | Raw Unified | Return to bug 229272
Collapse All | Expand All




<apidef name="csl.api">Common Scripting Language API</apidef>
</apidefs>
<changes>
    <change id="DocumentationUrl">
        <api name="csl.api"/>
        <summary>Provide a way to configure external documentation URL</summary>
        <version major="2" minor="43"/>
        <date day="9" month="9" year="2013"/>
        <author login="phejl"/>
        <compatibility addition="yes" deletion="no" modification="no" binary="compatible" source="compatible" deprecation="no"/>
        <description>
            <p>
                Extending code completion hadler to provide a way client may
                specify external documentation URL.
            </p>
        </description>
        <class package="org.netbeans.modules.csl.api" name="CodeCompletionHandler2"/>
        <class package="org.netbeans.modules.csl.api" name="Documentation"/>
        <issue number="229272"/>
    </change>
    <change id="LanguageRegistration.useMultiview">
        <api name="csl.api"/>
        <summary>Add useMultiview to @LanguageRegistration</summary>

Lines 40-46 Link Here

(-)a/csl.api/nbproject/project.properties (-1 / +1 lines)
40	# Version 2 license, then the option applies only if the new code is	40	# Version 2 license, then the option applies only if the new code is
41	# made subject to such option by the copyright holder.	41	# made subject to such option by the copyright holder.
42		42
43	spec.version.base=2.42.0	43	spec.version.base=2.43.0
44	is.autoload=true	44	is.autoload=true
45	javac.source=1.6	45	javac.source=1.6
46		46




/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright 2013 Oracle and/or its affiliates. All rights reserved.
 *
 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.
 * Other names may be trademarks of their respective owners.
 *
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common
 * Development and Distribution License("CDDL") (collectively, the
 * "License"). You may not use this file except in compliance with the
 * License. You can obtain a copy of the License at
 * http://www.netbeans.org/cddl-gplv2.html
 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
 * specific language governing permissions and limitations under the
 * License.  When distributing the software, include this License Header
 * Notice in each file and include the License file at
 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the GPL Version 2 section of the License file that
 * accompanied this code. If applicable, add the following below the
 * License Header, with the fields enclosed by brackets [] replaced by
 * your own identifying information:
 * "Portions Copyrighted [year] [name of copyright owner]"
 *
 * If you wish your version of this file to be governed by only the CDDL
 * or only the GPL Version 2, indicate your decision by adding
 * "[Contributor] elects to include this software in this distribution
 * under the [CDDL or GPL Version 2] license." If you do not indicate a
 * single choice of license, a recipient has the option to distribute
 * your version of this file under either the CDDL, the GPL Version 2 or
 * to extend the choice of license to its licensees as provided above.
 * However, if you add GPL Version 2 code and therefore, elected the GPL
 * Version 2 license, then the option applies only if the new code is
 * made subject to such option by the copyright holder.
 *
 * Contributor(s):
 *
 * Portions Copyrighted 2013 Sun Microsystems, Inc.
 */
package org.netbeans.modules.csl.api;

import org.netbeans.api.annotations.common.CheckForNull;
import org.netbeans.api.annotations.common.NonNull;
import org.netbeans.modules.csl.spi.ParserResult;

/**
 * Specifies additional method to {@link CodeCompletionHandler} providing
 * complete documentation for elements.
 *
 * @author Petr Hejl
 * @since 2.43
 */
public interface CodeCompletionHandler2 extends CodeCompletionHandler {

    /**
     * Provides a full documentation for the element. The infrastructure will
     * always prefer this method to the {@link CodeCompletionHandler#document(org.netbeans.modules.csl.spi.ParserResult, org.netbeans.modules.csl.api.ElementHandle)}.
     * The old method will be called as callback only if this one returns {@code null}.
     *
     * @param info the parsing information
     * @param element the element for which the documentation is requested
     * @return the documentation for the element
     */
    @CheckForNull
    Documentation documentElement(@NonNull ParserResult info, @NonNull ElementHandle element);
}




/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright 2013 Oracle and/or its affiliates. All rights reserved.
 *
 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.
 * Other names may be trademarks of their respective owners.
 *
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common
 * Development and Distribution License("CDDL") (collectively, the
 * "License"). You may not use this file except in compliance with the
 * License. You can obtain a copy of the License at
 * http://www.netbeans.org/cddl-gplv2.html
 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
 * specific language governing permissions and limitations under the
 * License.  When distributing the software, include this License Header
 * Notice in each file and include the License file at
 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the GPL Version 2 section of the License file that
 * accompanied this code. If applicable, add the following below the
 * License Header, with the fields enclosed by brackets [] replaced by
 * your own identifying information:
 * "Portions Copyrighted [year] [name of copyright owner]"
 *
 * If you wish your version of this file to be governed by only the CDDL
 * or only the GPL Version 2, indicate your decision by adding
 * "[Contributor] elects to include this software in this distribution
 * under the [CDDL or GPL Version 2] license." If you do not indicate a
 * single choice of license, a recipient has the option to distribute
 * your version of this file under either the CDDL, the GPL Version 2 or
 * to extend the choice of license to its licensees as provided above.
 * However, if you add GPL Version 2 code and therefore, elected the GPL
 * Version 2 license, then the option applies only if the new code is
 * made subject to such option by the copyright holder.
 *
 * Contributor(s):
 *
 * Portions Copyrighted 2013 Sun Microsystems, Inc.
 */
package org.netbeans.modules.csl.api;

import java.net.URL;
import org.netbeans.api.annotations.common.CheckForNull;
import org.netbeans.api.annotations.common.NonNull;
import org.openide.util.Parameters;

/**
 * Represents documentation displayed in code completion window.
 *
 * @author Petr Hejl
 * @since 2.43
 */
public final class Documentation {

    private final String content;

    private final URL url;

    private Documentation(String content, URL url) {
        assert content != null;
        this.content = content;
        this.url = url;
    }

    @NonNull
    public static Documentation create(@NonNull String content) {
        Parameters.notNull("content", content);
        return new Documentation(content, null);
    }

    @NonNull
    public static Documentation create(@NonNull String content, URL url) {
        Parameters.notNull("content", content);
        return new Documentation(content, url);
    }

    /**
     * The documentation itself.
     *
     * @return documentation itself
     */
    @NonNull
    public String getContent() {
        return content;
    }

    /**
     * The external documentation URL. Might be {@code null}.
     *
     * @return external documentation URL
     */
    @CheckForNull
    public URL getUrl() {
        return url;
    }

}

Lines 54-59 Link Here

(-)a/csl.api/src/org/netbeans/modules/csl/editor/completion/GsfCompletionDoc.java (-1 / +16 lines)
54		54
55	import org.netbeans.api.editor.completion.Completion;	55	import org.netbeans.api.editor.completion.Completion;
56	import org.netbeans.modules.csl.api.CodeCompletionHandler;	56	import org.netbeans.modules.csl.api.CodeCompletionHandler;
		57	import org.netbeans.modules.csl.api.CodeCompletionHandler2;
		58	import org.netbeans.modules.csl.api.Documentation;
57	import org.netbeans.modules.csl.api.ElementHandle;	59	import org.netbeans.modules.csl.api.ElementHandle;
58	import org.netbeans.modules.csl.api.UiUtils;	60	import org.netbeans.modules.csl.api.UiUtils;
59	import org.netbeans.modules.csl.core.LanguageRegistry;	61	import org.netbeans.modules.csl.core.LanguageRegistry;
Lines 107-113 Link Here
107	}	109	}
108		110
109	if (completer != null) {	111	if (completer != null) {
110	this.content = completer.document(controller, elementHandle);	112	if (completer instanceof CodeCompletionHandler2) {
		113	Documentation doc = ((CodeCompletionHandler2) completer).documentElement(controller, elementHandle);
		114	if (doc != null) {
		115	this.content = doc.getContent();
		116	if (docURL == null) {
		117	docURL = doc.getUrl();
		118	}
		119	} else {
		120	this.content = completer.document(controller, elementHandle);
		121	}
		122	} else {
		123	this.content = completer.document(controller, elementHandle);
		124	}
111	}	125	}
112		126
113	if (this.content == null) {	127	if (this.content == null) {
Lines 128-133 Link Here
128	return docURL;	142	return docURL;
129	}	143	}
130		144
		145	@Override
131	public CompletionDocumentation resolveLink(String link) {	146	public CompletionDocumentation resolveLink(String link) {
132	if (link.startsWith("www.")) {	147	if (link.startsWith("www.")) {
133	link = "http://" + link;	148	link = "http://" + link;

Lines 47-53 Link Here

(-)a/javascript2.editor/nbproject/project.xml (-1 / +1 lines)
47	<compile-dependency/>	47	<compile-dependency/>
48	<run-dependency>	48	<run-dependency>
49	<release-version>2</release-version>	49	<release-version>2</release-version>
50	<specification-version>2.25</specification-version>	50	<specification-version>2.43</specification-version>
51	</run-dependency>	51	</run-dependency>
52	</dependency>	52	</dependency>
53	<dependency>	53	<dependency>




import java.util.logging.Logger;
import javax.swing.text.Document;
import javax.swing.text.JTextComponent;
import org.netbeans.api.annotations.common.NullAllowed;
import org.netbeans.api.editor.EditorUtilities;
import org.netbeans.api.lexer.Language;
import org.netbeans.api.lexer.Token;
import org.netbeans.api.lexer.TokenHierarchy;
import org.netbeans.api.lexer.TokenId;

 *
 * @author Petr Pisl
 */
class JsCodeCompletion implements CodeCompletionHandler2 {

    private static final Logger LOGGER = Logger.getLogger(JsCodeCompletion.class.getName());



    @Override
    public String document(ParserResult info, ElementHandle element) {
        Documentation doc = documentElement(info, element);
        if (doc != null) {
            return doc.getContent();
        }
        return null;
    }

    @Override
    public Documentation documentElement(ParserResult info, ElementHandle element) {
        if (element instanceof IndexedElement) {
            final Documentation[] result = new Documentation[1];
            final IndexedElement indexedElement = (IndexedElement)element;
            FileObject nextFo = indexedElement.getFileObject();
            if (nextFo != null) {

                                JsObject jsObjectGlobal  = jsInfo.getModel().getGlobalObject();
                                JsObject property = ModelUtils.findJsObjectByName(jsObjectGlobal, fqn);
                                if (property != null) {
                                    Documentation doc = property.getDocumentation();
                                    result[0] = doc;
                                        documentation.append(doc);
                                    }
                                }

                            } else {

                    LOGGER.log(Level.WARNING, null, ex);
                }
            }
            if (result[0] != null) {
                return result[0];
            }
        } else if (element instanceof JsObject) {
            JsObject jsObject = (JsObject) element;
            if (jsObject.getDocumentation() != null) {
                return jsObject.getDocumentation();
            }
        }

        for (CompletionProvider interceptor : EditorExtender.getDefault().getCompletionProviders()) {
            String doc = interceptor.getHelpDocumentation(info, element);
            if (doc != null && !doc.isEmpty()) {
                return Documentation.create(doc);
                }
            }
        }

        if (element instanceof JsDocumentationElement) {
            return Documentation.create(((JsDocumentationElement) element).getDocumentation());
        }

        return Documentation.create(NbBundle.getMessage(JsCodeCompletion.class, "MSG_DocNotAvailable"));
        }
        return documentation.toString();
    }

    

Lines 104-109 Link Here

(-)a/javascript2.editor/src/org/netbeans/modules/javascript2/editor/doc/JsDocumentationElement.java (+1 lines)
104	return OffsetRange.NONE;	104	return OffsetRange.NONE;
105	}	105	}
106		106
		107	// XXX csl Documentation usage ?
107	public String getDocumentation() {	108	public String getDocumentation() {
108	return documentation;	109	return documentation;
109	}	110	}

Lines 46-51 Link Here

(-)a/javascript2.editor/src/org/netbeans/modules/javascript2/editor/doc/JsDocumentationFallbackHolder.java (-2 / +3 lines)
46	import java.util.List;	46	import java.util.List;
47	import java.util.Map;	47	import java.util.Map;
48	import java.util.Set;	48	import java.util.Set;
		49	import org.netbeans.modules.csl.api.Documentation;
49	import org.netbeans.modules.javascript2.editor.doc.spi.JsDocumentationHolder;	50	import org.netbeans.modules.javascript2.editor.doc.spi.JsDocumentationHolder;
50	import org.netbeans.modules.javascript2.editor.doc.spi.JsDocumentationProvider;	51	import org.netbeans.modules.javascript2.editor.doc.spi.JsDocumentationProvider;
51	import org.netbeans.modules.parsing.api.Snapshot;	52	import org.netbeans.modules.parsing.api.Snapshot;
Lines 73-80 Link Here
73	}	74	}
74		75
75	@Override	76	@Override
76	public String getDocumentation(Node node) {	77	public Documentation getDocumentation(Node node) {
77	return "";	78	return null;
78	}	79	}
79		80
80	@Override	81	@Override

Lines 51-56 Link Here

(-)a/javascript2.editor/src/org/netbeans/modules/javascript2/editor/doc/spi/JsDocumentationHolder.java (-2 / +6 lines)
51	import org.netbeans.api.lexer.Token;	51	import org.netbeans.api.lexer.Token;
52	import org.netbeans.api.lexer.TokenHierarchy;	52	import org.netbeans.api.lexer.TokenHierarchy;
53	import org.netbeans.api.lexer.TokenSequence;	53	import org.netbeans.api.lexer.TokenSequence;
		54	import org.netbeans.modules.csl.api.Documentation;
54	import org.netbeans.modules.csl.api.OffsetRange;	55	import org.netbeans.modules.csl.api.OffsetRange;
55	import org.netbeans.modules.javascript2.editor.doc.DocumentationUtils;	56	import org.netbeans.modules.javascript2.editor.doc.DocumentationUtils;
56	import org.netbeans.modules.javascript2.editor.doc.JsDocumentationPrinter;	57	import org.netbeans.modules.javascript2.editor.doc.JsDocumentationPrinter;
Lines 150-159 Link Here
150	* @param node of the javaScript code	151	* @param node of the javaScript code
151	* @return documentation text if any {@code null} otherwise	152	* @return documentation text if any {@code null} otherwise
152	*/	153	*/
153	public String getDocumentation(Node node) {	154	public Documentation getDocumentation(Node node) {
154	JsComment comment = getCommentForOffset(node.getStart(), getCommentBlocks());	155	JsComment comment = getCommentForOffset(node.getStart(), getCommentBlocks());
155	if (comment != null) {	156	if (comment != null) {
156	return JsDocumentationPrinter.printDocumentation(comment);	157	String content = JsDocumentationPrinter.printDocumentation(comment);
		158	if (!content.isEmpty()) {
		159	return Documentation.create(content);
		160	}
157	}	161	}
158	return null;	162	return null;
159	}	163	}

Lines 44-49 Link Here

(-)a/javascript2.editor/src/org/netbeans/modules/javascript2/editor/model/JsObject.java (-1 / +2 lines)
44	import java.util.Collection;	44	import java.util.Collection;
45	import java.util.List;	45	import java.util.List;
46	import java.util.Map;	46	import java.util.Map;
		47	import org.netbeans.modules.csl.api.Documentation;
47	import org.netbeans.modules.csl.api.OffsetRange;	48	import org.netbeans.modules.csl.api.OffsetRange;
48		49
49	/**	50	/**
Lines 88-92 Link Here
88	*/	89	*/
89	public boolean hasExactName();	90	public boolean hasExactName();
90		91
91	public String getDocumentation();	92	public Documentation getDocumentation();
92	}	93	}





import java.util.*;
import jdk.nashorn.internal.objects.PrototypeObject;
import org.netbeans.modules.csl.api.Documentation;
import org.netbeans.modules.csl.api.Modifier;
import org.netbeans.modules.csl.api.OffsetRange;
import org.netbeans.modules.javascript2.editor.doc.spi.JsDocumentationHolder;

    final private List<Occurrence> occurrences = new ArrayList<Occurrence>();
    final private NavigableMap<Integer, Collection<TypeUsage>> assignments = new TreeMap<Integer, Collection<TypeUsage>>();
    final private boolean hasName;
    private Documentation documentation;
    protected JsElement.Kind kind;
    
    public JsObjectImpl(JsObject parent, Identifier name, OffsetRange offsetRange,

    }

    @Override
    public Documentation getDocumentation() {
        return documentation;
    }
 
    public void setDocumentation(Documentation doc) {
        this.documentation = doc;
    }


Lines 46-51 Link Here

(-)a/javascript2.editor/src/org/netbeans/modules/javascript2/editor/model/impl/JsObjectReference.java (-1 / +2 lines)
46	import java.util.Map;	46	import java.util.Map;
47	import java.util.Set;	47	import java.util.Set;
48	import org.netbeans.api.annotations.common.NonNull;	48	import org.netbeans.api.annotations.common.NonNull;
		49	import org.netbeans.modules.csl.api.Documentation;
49	import org.netbeans.modules.csl.api.ElementKind;	50	import org.netbeans.modules.csl.api.ElementKind;
50	import org.netbeans.modules.csl.api.Modifier;	51	import org.netbeans.modules.csl.api.Modifier;
51	import org.netbeans.modules.javascript2.editor.doc.spi.JsDocumentationHolder;	52	import org.netbeans.modules.javascript2.editor.doc.spi.JsDocumentationHolder;
Lines 134-140 Link Here
134	}	135	}
135		136
136	@Override	137	@Override
137	public String getDocumentation() {	138	public Documentation getDocumentation() {
138	return original.getDocumentation();	139	return original.getDocumentation();
139	}	140	}
140		141

Lines 42-47 Link Here

(-)a/javascript2.editor/src/org/netbeans/modules/javascript2/editor/model/impl/ParameterObject.java (-2 / +6 lines)
42	package org.netbeans.modules.javascript2.editor.model.impl;	42	package org.netbeans.modules.javascript2.editor.model.impl;
43		43
44	import java.util.Collections;	44	import java.util.Collections;
		45	import org.netbeans.modules.csl.api.Documentation;
45	import org.netbeans.modules.javascript2.editor.doc.JsDocumentationPrinter;	46	import org.netbeans.modules.javascript2.editor.doc.JsDocumentationPrinter;
46	import org.netbeans.modules.javascript2.editor.doc.spi.DocParameter;	47	import org.netbeans.modules.javascript2.editor.doc.spi.DocParameter;
47	import org.netbeans.modules.javascript2.editor.doc.spi.JsComment;	48	import org.netbeans.modules.javascript2.editor.doc.spi.JsComment;
Lines 82-88 Link Here
82	}	83	}
83		84
84	@Override	85	@Override
85	public String getDocumentation() {	86	public Documentation getDocumentation() {
86	final String[] result = new String[1];	87	final String[] result = new String[1];
87	try {	88	try {
88	ParserManager.parse(Collections.singleton(Source.create(getParent().getFileObject())), new UserTask() {	89	ParserManager.parse(Collections.singleton(Source.create(getParent().getFileObject())), new UserTask() {
Lines 106-111 Link Here
106	} catch (ParseException ex) {	107	} catch (ParseException ex) {
107	Exceptions.printStackTrace(ex);	108	Exceptions.printStackTrace(ex);
108	}	109	}
109	return result[0];	110	if (result[0] != null && !result[0].isEmpty()) {
		111	return Documentation.create(result[0]);
		112	}
		113	return null;
110	}	114	}
111	}	115	}




import java.util.Map;
import java.util.Set;
import org.netbeans.api.annotations.common.NullAllowed;
import org.netbeans.modules.csl.api.Documentation;
import org.netbeans.modules.csl.api.ElementHandle;
import org.netbeans.modules.csl.api.ElementKind;
import org.netbeans.modules.csl.api.Modifier;

        }

        @Override
        public Documentation getDocumentation() {
            return delegate.getDocumentation();
        }


        }

        @Override
        public Documentation getDocumentation() {
            return delegate.getDocumentation();
        }


Lines 82-88 Link Here

(-)a/javascript2.editor/test/unit/src/org/netbeans/modules/javascript2/editor/extdoc/ExtDocCompletionDocumentationTest.java (-1 / +1 lines)
82	Source testSource = getTestSource(getTestFile(relPath));	82	Source testSource = getTestSource(getTestFile(relPath));
83	final int caretOffset = getCaretOffset(testSource, caretSeeker);	83	final int caretOffset = getCaretOffset(testSource, caretSeeker);
84	initializeDocumentationHolder(testSource);	84	initializeDocumentationHolder(testSource);
85	assertDescriptionMatches(relPath, documentationHolder.getDocumentation(getNodeForOffset(parserResult, caretOffset)), true, "completionDoc.html");	85	assertDescriptionMatches(relPath, documentationHolder.getDocumentation(getNodeForOffset(parserResult, caretOffset)).getContent(), true, "completionDoc.html");
86	}	86	}
87		87
88	public void testCompletionDocumentation01() throws Exception {	88	public void testCompletionDocumentation01() throws Exception {

Lines 82-88 Link Here

(-)a/javascript2.editor/test/unit/src/org/netbeans/modules/javascript2/editor/jsdoc/JsDocCompletionDocumentationTest.java (-1 / +1 lines)
82	Source testSource = getTestSource(getTestFile(relPath));	82	Source testSource = getTestSource(getTestFile(relPath));
83	final int caretOffset = getCaretOffset(testSource, caretSeeker);	83	final int caretOffset = getCaretOffset(testSource, caretSeeker);
84	initializeDocumentationHolder(testSource);	84	initializeDocumentationHolder(testSource);
85	assertDescriptionMatches(relPath, documentationHolder.getDocumentation(getNodeForOffset(parserResult, caretOffset)), true, "completionDoc.html");	85	assertDescriptionMatches(relPath, documentationHolder.getDocumentation(getNodeForOffset(parserResult, caretOffset)).getContent(), true, "completionDoc.html");
86	}	86	}
87		87
88	public void testCompletionDocumentation01() throws Exception {	88	public void testCompletionDocumentation01() throws Exception {

Lines 83-89 Link Here

(-)a/javascript2.editor/test/unit/src/org/netbeans/modules/javascript2/editor/sdoc/SDocCompletionDocumentationTest.java (-1 / +1 lines)
83	Source testSource = getTestSource(getTestFile(relPath));	83	Source testSource = getTestSource(getTestFile(relPath));
84	final int caretOffset = getCaretOffset(testSource, caretSeeker);	84	final int caretOffset = getCaretOffset(testSource, caretSeeker);
85	initializeDocumentationHolder(testSource);	85	initializeDocumentationHolder(testSource);
86	assertDescriptionMatches(relPath, documentationHolder.getDocumentation(getNodeForOffset(parserResult, caretOffset)), true, "completionDoc.html");	86	assertDescriptionMatches(relPath, documentationHolder.getDocumentation(getNodeForOffset(parserResult, caretOffset)).getContent(), true, "completionDoc.html");
87	}	87	}
88		88
89	public void testCompletionDocumentation01() throws Exception {	89	public void testCompletionDocumentation01() throws Exception {

Return to bug 229272

Lines 46-54 Link Here

(-)a/javascript2.editor/src/org/netbeans/modules/javascript2/editor/JsCodeCompletion.java (-22 / +27 lines)
46	import java.util.logging.Logger;	46	import java.util.logging.Logger;
47	import javax.swing.text.Document;	47	import javax.swing.text.Document;
48	import javax.swing.text.JTextComponent;	48	import javax.swing.text.JTextComponent;
49	import org.netbeans.api.annotations.common.NullAllowed;
50	import org.netbeans.api.editor.EditorUtilities;
51	import org.netbeans.api.lexer.Language;
52	import org.netbeans.api.lexer.Token;	49	import org.netbeans.api.lexer.Token;
53	import org.netbeans.api.lexer.TokenHierarchy;	50	import org.netbeans.api.lexer.TokenHierarchy;
54	import org.netbeans.api.lexer.TokenId;	51	import org.netbeans.api.lexer.TokenId;
Lines 89-95 Link Here
89	*	86	*
90	* @author Petr Pisl	87	* @author Petr Pisl
91	*/	88	*/
92	class JsCodeCompletion implements CodeCompletionHandler {	89	class JsCodeCompletion implements CodeCompletionHandler2 {
93		90
94	private static final Logger LOGGER = Logger.getLogger(JsCodeCompletion.class.getName());	91	private static final Logger LOGGER = Logger.getLogger(JsCodeCompletion.class.getName());
95		92
Lines 233-240 Link Here
233		230
234	@Override	231	@Override
235	public String document(ParserResult info, ElementHandle element) {	232	public String document(ParserResult info, ElementHandle element) {
236	final StringBuilder documentation = new StringBuilder();	233	Documentation doc = documentElement(info, element);
237	if(element instanceof IndexedElement) {	234	if (doc != null) {
		235	return doc.getContent();
		236	}
		237	return null;
		238	}
		239
		240	@Override
		241	public Documentation documentElement(ParserResult info, ElementHandle element) {
		242	if (element instanceof IndexedElement) {
		243	final Documentation[] result = new Documentation[1];
238	final IndexedElement indexedElement = (IndexedElement)element;	244	final IndexedElement indexedElement = (IndexedElement)element;
239	FileObject nextFo = indexedElement.getFileObject();	245	FileObject nextFo = indexedElement.getFileObject();
240	if (nextFo != null) {	246	if (nextFo != null) {
Lines 251-260 Link Here
251	JsObject jsObjectGlobal = jsInfo.getModel().getGlobalObject();	257	JsObject jsObjectGlobal = jsInfo.getModel().getGlobalObject();
252	JsObject property = ModelUtils.findJsObjectByName(jsObjectGlobal, fqn);	258	JsObject property = ModelUtils.findJsObjectByName(jsObjectGlobal, fqn);
253	if (property != null) {	259	if (property != null) {
254	String doc = property.getDocumentation();	260	Documentation doc = property.getDocumentation();
255	if (doc != null && !doc.isEmpty()) {	261	result[0] = doc;
256	documentation.append(doc);
257	}
258	}	262	}
259		263
260	} else {	264	} else {
Lines 267-293 Link Here
267	LOGGER.log(Level.WARNING, null, ex);	271	LOGGER.log(Level.WARNING, null, ex);
268	}	272	}
269	}	273	}
		274	if (result[0] != null) {
		275	return result[0];
		276	}
270	} else if (element instanceof JsObject) {	277	} else if (element instanceof JsObject) {
271	JsObject jsObject = (JsObject) element;	278	JsObject jsObject = (JsObject) element;
272	if (jsObject.getDocumentation() != null) {	279	if (jsObject.getDocumentation() != null) {
273	documentation.append(jsObject.getDocumentation());	280	return jsObject.getDocumentation();
274	}	281	}
275	}	282	}
276	if (documentation.length() == 0) {	283
277	for (CompletionProvider interceptor : EditorExtender.getDefault().getCompletionProviders()) {	284	for (CompletionProvider interceptor : EditorExtender.getDefault().getCompletionProviders()) {
278	String doc = interceptor.getHelpDocumentation(info, element);	285	String doc = interceptor.getHelpDocumentation(info, element);
279	if (doc != null && !doc.isEmpty()) {	286	if (doc != null && !doc.isEmpty()) {
280	documentation.append(doc);	287	return Documentation.create(doc);
281	}
282	}	288	}
283	}	289	}
		290
284	if (element instanceof JsDocumentationElement) {	291	if (element instanceof JsDocumentationElement) {
285	return ((JsDocumentationElement) element).getDocumentation();	292	return Documentation.create(((JsDocumentationElement) element).getDocumentation());
286	}	293	}
287	if (documentation.length() == 0) {	294
288	documentation.append(NbBundle.getMessage(JsCodeCompletion.class, "MSG_DocNotAvailable"));	295	return Documentation.create(NbBundle.getMessage(JsCodeCompletion.class, "MSG_DocNotAvailable"));
289	}
290	return documentation.toString();
291	}	296	}
292		297
293		298

Lines 49-54 Link Here

(-)a/csl.api/apichanges.xml (+17 lines)
49	<apidef name="csl.api">Common Scripting Language API</apidef>	49	<apidef name="csl.api">Common Scripting Language API</apidef>
50	</apidefs>	50	</apidefs>
51	<changes>	51	<changes>
		52	<change id="DocumentationUrl">
		53	<api name="csl.api"/>
		54	<summary>Provide a way to configure external documentation URL</summary>
		55	<version major="2" minor="43"/>
		56	<date day="9" month="9" year="2013"/>
		57	<author login="phejl"/>
		58	<compatibility addition="yes" deletion="no" modification="no" binary="compatible" source="compatible" deprecation="no"/>
		59	<description>
		60	<p>
		61	Extending code completion hadler to provide a way client may
		62	specify external documentation URL.
		63	</p>
		64	</description>
		65	<class package="org.netbeans.modules.csl.api" name="CodeCompletionHandler2"/>
		66	<class package="org.netbeans.modules.csl.api" name="Documentation"/>
		67	<issue number="229272"/>
		68	</change>
52	<change id="LanguageRegistration.useMultiview">	69	<change id="LanguageRegistration.useMultiview">
53	<api name="csl.api"/>	70	<api name="csl.api"/>
54	<summary>Add useMultiview to @LanguageRegistration</summary>	71	<summary>Add useMultiview to @LanguageRegistration</summary>

Added Link Here

(-)2f2cffb4aab7 (+68 lines)
1	/*
2	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3	*
4	* Copyright 2013 Oracle and/or its affiliates. All rights reserved.
5	*
6	* Oracle and Java are registered trademarks of Oracle and/or its affiliates.
7	* Other names may be trademarks of their respective owners.
8	*
9	* The contents of this file are subject to the terms of either the GNU
10	* General Public License Version 2 only ("GPL") or the Common
11	* Development and Distribution License("CDDL") (collectively, the
12	* "License"). You may not use this file except in compliance with the
13	* License. You can obtain a copy of the License at
14	* http://www.netbeans.org/cddl-gplv2.html
15	* or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
16	* specific language governing permissions and limitations under the
17	* License. When distributing the software, include this License Header
18	* Notice in each file and include the License file at
19	* nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this
20	* particular file as subject to the "Classpath" exception as provided
21	* by Oracle in the GPL Version 2 section of the License file that
22	* accompanied this code. If applicable, add the following below the
23	* License Header, with the fields enclosed by brackets [] replaced by
24	* your own identifying information:
25	* "Portions Copyrighted [year] [name of copyright owner]"
26	*
27	* If you wish your version of this file to be governed by only the CDDL
28	* or only the GPL Version 2, indicate your decision by adding
29	* "[Contributor] elects to include this software in this distribution
30	* under the [CDDL or GPL Version 2] license." If you do not indicate a
31	* single choice of license, a recipient has the option to distribute
32	* your version of this file under either the CDDL, the GPL Version 2 or
33	* to extend the choice of license to its licensees as provided above.
34	* However, if you add GPL Version 2 code and therefore, elected the GPL
35	* Version 2 license, then the option applies only if the new code is
36	* made subject to such option by the copyright holder.
37	*
38	* Contributor(s):
39	*
40	* Portions Copyrighted 2013 Sun Microsystems, Inc.
41	*/
42	package org.netbeans.modules.csl.api;
43
44	import org.netbeans.api.annotations.common.CheckForNull;
45	import org.netbeans.api.annotations.common.NonNull;
46	import org.netbeans.modules.csl.spi.ParserResult;
47
48	/**
49	* Specifies additional method to {@link CodeCompletionHandler} providing
50	* complete documentation for elements.
51	*
52	* @author Petr Hejl
53	* @since 2.43
54	*/
55	public interface CodeCompletionHandler2 extends CodeCompletionHandler {
56
57	/**
58	* Provides a full documentation for the element. The infrastructure will
59	* always prefer this method to the {@link CodeCompletionHandler#document(org.netbeans.modules.csl.spi.ParserResult, org.netbeans.modules.csl.api.ElementHandle)}.
60	* The old method will be called as callback only if this one returns {@code null}.
61	*
62	* @param info the parsing information
63	* @param element the element for which the documentation is requested
64	* @return the documentation for the element
65	*/
66	@CheckForNull
67	Documentation documentElement(@NonNull ParserResult info, @NonNull ElementHandle element);
68	}

Added Link Here

(-)2f2cffb4aab7 (+99 lines)
1	/*
2	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3	*
4	* Copyright 2013 Oracle and/or its affiliates. All rights reserved.
5	*
6	* Oracle and Java are registered trademarks of Oracle and/or its affiliates.
7	* Other names may be trademarks of their respective owners.
8	*
9	* The contents of this file are subject to the terms of either the GNU
10	* General Public License Version 2 only ("GPL") or the Common
11	* Development and Distribution License("CDDL") (collectively, the
12	* "License"). You may not use this file except in compliance with the
13	* License. You can obtain a copy of the License at
14	* http://www.netbeans.org/cddl-gplv2.html
15	* or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
16	* specific language governing permissions and limitations under the
17	* License. When distributing the software, include this License Header
18	* Notice in each file and include the License file at
19	* nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this
20	* particular file as subject to the "Classpath" exception as provided
21	* by Oracle in the GPL Version 2 section of the License file that
22	* accompanied this code. If applicable, add the following below the
23	* License Header, with the fields enclosed by brackets [] replaced by
24	* your own identifying information:
25	* "Portions Copyrighted [year] [name of copyright owner]"
26	*
27	* If you wish your version of this file to be governed by only the CDDL
28	* or only the GPL Version 2, indicate your decision by adding
29	* "[Contributor] elects to include this software in this distribution
30	* under the [CDDL or GPL Version 2] license." If you do not indicate a
31	* single choice of license, a recipient has the option to distribute
32	* your version of this file under either the CDDL, the GPL Version 2 or
33	* to extend the choice of license to its licensees as provided above.
34	* However, if you add GPL Version 2 code and therefore, elected the GPL
35	* Version 2 license, then the option applies only if the new code is
36	* made subject to such option by the copyright holder.
37	*
38	* Contributor(s):
39	*
40	* Portions Copyrighted 2013 Sun Microsystems, Inc.
41	*/
42	package org.netbeans.modules.csl.api;
43
44	import java.net.URL;
45	import org.netbeans.api.annotations.common.CheckForNull;
46	import org.netbeans.api.annotations.common.NonNull;
47	import org.openide.util.Parameters;
48
49	/**
50	* Represents documentation displayed in code completion window.
51	*
52	* @author Petr Hejl
53	* @since 2.43
54	*/
55	public final class Documentation {
56
57	private final String content;
58
59	private final URL url;
60
61	private Documentation(String content, URL url) {
62	assert content != null;
63	this.content = content;
64	this.url = url;
65	}
66
67	@NonNull
68	public static Documentation create(@NonNull String content) {
69	Parameters.notNull("content", content);
70	return new Documentation(content, null);
71	}
72
73	@NonNull
74	public static Documentation create(@NonNull String content, URL url) {
75	Parameters.notNull("content", content);
76	return new Documentation(content, url);
77	}
78
79	/**
80	* The documentation itself.
81	*
82	* @return documentation itself
83	*/
84	@NonNull
85	public String getContent() {
86	return content;
87	}
88
89	/**
90	* The external documentation URL. Might be {@code null}.
91	*
92	* @return external documentation URL
93	*/
94	@CheckForNull
95	public URL getUrl() {
96	return url;
97	}
98
99	}

Lines 43-48 Link Here

(-)a/javascript2.editor/src/org/netbeans/modules/javascript2/editor/model/impl/JsObjectImpl.java (-3 / +4 lines)
43		43
44	import java.util.*;	44	import java.util.*;
45	import jdk.nashorn.internal.objects.PrototypeObject;	45	import jdk.nashorn.internal.objects.PrototypeObject;
		46	import org.netbeans.modules.csl.api.Documentation;
46	import org.netbeans.modules.csl.api.Modifier;	47	import org.netbeans.modules.csl.api.Modifier;
47	import org.netbeans.modules.csl.api.OffsetRange;	48	import org.netbeans.modules.csl.api.OffsetRange;
48	import org.netbeans.modules.javascript2.editor.doc.spi.JsDocumentationHolder;	49	import org.netbeans.modules.javascript2.editor.doc.spi.JsDocumentationHolder;
Lines 60-66 Link Here
60	final private List<Occurrence> occurrences = new ArrayList<Occurrence>();	61	final private List<Occurrence> occurrences = new ArrayList<Occurrence>();
61	final private NavigableMap<Integer, Collection<TypeUsage>> assignments = new TreeMap<Integer, Collection<TypeUsage>>();	62	final private NavigableMap<Integer, Collection<TypeUsage>> assignments = new TreeMap<Integer, Collection<TypeUsage>>();
62	final private boolean hasName;	63	final private boolean hasName;
63	private String documentation;	64	private Documentation documentation;
64	protected JsElement.Kind kind;	65	protected JsElement.Kind kind;
65		66
66	public JsObjectImpl(JsObject parent, Identifier name, OffsetRange offsetRange,	67	public JsObjectImpl(JsObject parent, Identifier name, OffsetRange offsetRange,
Lines 590-600 Link Here
590	}	591	}
591		592
592	@Override	593	@Override
593	public String getDocumentation() {	594	public Documentation getDocumentation() {
594	return documentation;	595	return documentation;
595	}	596	}
596		597
597	public void setDocumentation(String doc) {	598	public void setDocumentation(Documentation doc) {
598	this.documentation = doc;	599	this.documentation = doc;
599	}	600	}
600		601