Mercurial > hg > truffle
changeset 22060:c0d4ec7e69c0
Properly classifying the API packages
author | Jaroslav Tulach <jaroslav.tulach@oracle.com> |
---|---|
date | Wed, 05 Aug 2015 14:17:24 +0200 |
parents | cc84642d989f |
children | 0bd14859636f |
files | truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/package-info.java truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/debug/package-info.java truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/frame/package-info.java truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/nodes/package-info.java truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/package-info.java truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/source/package-info.java truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/vm/package-info.java truffle/com.oracle.truffle.tools.debug.shell/src/com/oracle/truffle/tools/debug/shell/package-info.java |
diffstat | 8 files changed, 36 insertions(+), 127 deletions(-) [+] |
line wrap: on
line diff
--- a/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/package-info.java Tue Aug 04 22:50:40 2015 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,68 +0,0 @@ -/* - * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved. - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. - * - * This code is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License version 2 only, as - * published by the Free Software Foundation. - * - * This code is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * version 2 for more details (a copy is included in the LICENSE file that - * accompanied this code). - * - * You should have received a copy of the GNU General Public License version - * 2 along with this work; if not, write to the Free Software Foundation, - * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. - * - * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA - * or visit www.oracle.com if you need additional information or have any - * questions. - */ -/** - * <p> - * This package contains basic tests of the Truffle API and serves at the same time as an - * introduction to the Truffle API for language implementors. Every test gives an example on how to - * use the construct explained in the class description. - * </p> - * - * <p> - * Truffle is a language implementation framework. A guest language method is represented as a tree - * of executable nodes. The framework provides mechanisms for those trees to call each other. - * Additionally it contains dedicated data structures for storing data local to a tree invocation. - * </p> - * - * <p> - * This introduction to Truffle contains items in the following recommended order: - * - * <ul> - * <li>How to get access to the Truffle runtime? - * {@link com.oracle.truffle.api.test.TruffleRuntimeTest}</li> - * <li>How to create a root node? {@link com.oracle.truffle.api.test.RootNodeTest}</li> - * <li>How to create a child node and link it with its parent? - * {@link com.oracle.truffle.api.test.ChildNodeTest}</li> - * <li>How to create an array of child nodes? {@link com.oracle.truffle.api.test.ChildrenNodesTest} - * </li> - * <li>Why are final fields in node classes important? - * {@link com.oracle.truffle.api.test.FinalFieldTest}</li> - * <li>How to replace one node with another node and what for? - * {@link com.oracle.truffle.api.test.ReplaceTest}</li> - * <li>How to let one Truffle tree invoke another one? {@link com.oracle.truffle.api.test.CallTest} - * </li> - * <li>How to pass arguments when executing a tree? - * {@link com.oracle.truffle.api.test.ArgumentsTest}</li> - * <li>How to use frames and frame slots to store values local to an activation? - * {@link com.oracle.truffle.api.test.FrameTest}</li> - * <li>How to use type specialization and speculation for frame slots? - * {@link com.oracle.truffle.api.test.FrameSlotTypeSpecializationTest}</li> - * <li>How to use type specialization and speculation for node return values? - * {@link com.oracle.truffle.api.test.ReturnTypeSpecializationTest}</li> - * <li>How to "instrument" an AST with nodes that can provide access to runtime state from external - * tools {@code com.oracle.truffle.api.test.instrument.InstrumentationTest}</li> - * </ul> - * - * - */ -package com.oracle.truffle.api.test; -
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/debug/package-info.java Tue Aug 04 22:50:40 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/debug/package-info.java Wed Aug 05 14:17:24 2015 +0200 @@ -23,6 +23,12 @@ * questions. */ +/* + @ApiInfo( + group="Stable" + ) + */ + /** * Control over {@link com.oracle.truffle.api.debug.Debugger debugging} of your {@link com.oracle.truffle.api.vm.TruffleVM}. Each {@link com.oracle.truffle.api.vm.TruffleVM} * is inherently capable to run in debugging mode - there is just one thing
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/frame/package-info.java Tue Aug 04 22:50:40 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/frame/package-info.java Wed Aug 05 14:17:24 2015 +0200 @@ -23,6 +23,12 @@ * questions. */ +/* + @ApiInfo( + group="To Review" + ) + */ + /** * Representation of a {@link com.oracle.truffle.api.frame.Frame stack frame}. While * {@link com.oracle.truffle.api.TruffleLanguage based language} is executing its stack parameters
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/nodes/package-info.java Tue Aug 04 22:50:40 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/nodes/package-info.java Wed Aug 05 14:17:24 2015 +0200 @@ -23,6 +23,12 @@ * questions. */ +/* + @ApiInfo( + group="To Review" + ) + */ + /** * Abstract syntax tree {@link com.oracle.truffle.api.nodes.Node nodes} are the basic building block * for your {@link com.oracle.truffle.api.TruffleLanguage}.
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/package-info.java Tue Aug 04 22:50:40 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/package-info.java Wed Aug 05 14:17:24 2015 +0200 @@ -23,6 +23,12 @@ * questions. */ +/* + @ApiInfo( + group="To Review" + ) + */ + /** * Do you want to implement your own {@link com.oracle.truffle.api.TruffleLanguage Truffle based * language}? In such case start {@link com.oracle.truffle.api.TruffleLanguage here}.
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/source/package-info.java Tue Aug 04 22:50:40 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/source/package-info.java Wed Aug 05 14:17:24 2015 +0200 @@ -23,6 +23,12 @@ * questions. */ +/* + @ApiInfo( + group="Stable" + ) + */ + /** * Represents a {@link com.oracle.truffle.api.source.Source source file}. */
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/vm/package-info.java Tue Aug 04 22:50:40 2015 -0700 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/vm/package-info.java Wed Aug 05 14:17:24 2015 +0200 @@ -23,6 +23,12 @@ * questions. */ +/* + @ApiInfo( + group="Stable" + ) + */ + /** * Central place to create and control {@link com.oracle.truffle.api.vm.TruffleVM Truffle Virtual * Machine} and all languages hosted in it.
--- a/truffle/com.oracle.truffle.tools.debug.shell/src/com/oracle/truffle/tools/debug/shell/package-info.java Tue Aug 04 22:50:40 2015 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,59 +0,0 @@ -/* - * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. - * - * This code is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License version 2 only, as - * published by the Free Software Foundation. Oracle designates this - * particular file as subject to the "Classpath" exception as provided - * by Oracle in the LICENSE file that accompanied this code. - * - * This code is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * version 2 for more details (a copy is included in the LICENSE file that - * accompanied this code). - * - * You should have received a copy of the GNU General Public License version - * 2 along with this work; if not, write to the Free Software Foundation, - * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. - * - * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA - * or visit www.oracle.com if you need additional information or have any - * questions. - */ - -/** - * This package contains an experimental framework for building simple command-line oriented - * debuggers that work with Truffle-implemented languages; it is used mainly for testing Truffle's - * built-in , which actually provides the - * debugging services. - * <p> - * Truffle debugging is made possible by the general purpose Instrumentation Framework built into - * the Truffle platform. Some online documentation for the Instrumentation Framework is available - * online: - * <quote> <a href="https://wiki.openjdk.java.net/display/Graal/Instrumentation+API">https://wiki. - * openjdk.java.net/display/Graal/Instrumentation+API</a> </quote> - * <p> - * Building one of these command line debuggers requires creating language-specific instances of: - * <ol> - * <li>DebugEngine, noting that this instance also - * depends on related services provided by the language implementation,</li> - * <li>{@link com.oracle.truffle.tools.debug.shell.REPLServer}, best accomplished by copying the - * implementation for Truffle's demonstration language "Simple" (a.k.a. "SL").</li> - * </ol> - * - * <strong>Disclaimer: </strong> although these command line debuggers are useful, they are not - * intended, and will not be maintained as, fully functioning debuggers. They should be considered - * valuable tools for the maintainers of the - * DebugEngine, as well as for Truffle language - * implementors for whom concurrent access to any kind debugging services can be quite helpful. - * <p> - * <strong>Note:</strong> Both the functionality and API for this package are under active - * development. - * <p> - * - * @see com.oracle.truffle.api.instrument - */ -package com.oracle.truffle.tools.debug.shell; -