/*
*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package org.apache.flex.compiler.codegen.js.goog;
import org.apache.flex.compiler.codegen.js.IJSDocEmitter;
import org.apache.flex.compiler.definitions.IClassDefinition;
import org.apache.flex.compiler.definitions.IDefinition;
import org.apache.flex.compiler.definitions.ITypeDefinition;
import org.apache.flex.compiler.projects.ICompilerProject;
import org.apache.flex.compiler.tree.as.IASNode;
import org.apache.flex.compiler.tree.as.IDefinitionNode;
import org.apache.flex.compiler.tree.as.IFunctionNode;
import org.apache.flex.compiler.tree.as.IInterfaceNode;
import org.apache.flex.compiler.tree.as.IParameterNode;
import org.apache.flex.compiler.tree.as.IVariableNode;
/**
* The {@link IJSGoogDocEmitter} interface allows the abstraction of JavaScript
* document comments to be emitted per tag.
* <p>
* The purpose of the API is to clamp emitted output to JavaScript doc tags. The
* output can be multiline but is specific to one tag. This allows a full
* comment to be created without worrying about how to assemble the tags.
* <p>
* The current tags were found at
* https://developers.google.com/closure/compiler/docs/js-for-compiler#types
* <p>
* TODO (mschmalle) Might make a comment API and tag API so comments are not
* dependent on tag creation IE IJSDocEmitter and IJSDocTagEmitter
*
* @author Michael Schmalle
*/
public interface IJSGoogDocEmitter extends IJSDocEmitter
{
void emitInterfaceDoc(IInterfaceNode node, ICompilerProject project);
void emitInterfaceMemberDoc(IDefinitionNode node, ICompilerProject project);
void emitFieldDoc(IVariableNode node, IDefinition def, ICompilerProject project);
void emitMethodDoc(IFunctionNode node, ICompilerProject project);
void emitVarDoc(IVariableNode node, IDefinition def, ICompilerProject project);
/*
* https://developers.google.com/closure/compiler/docs/js-for-compiler#types
*- @const - Marks a variable as read-only. The compiler can inline @const variables
*
*- @define - Indicates a constant that can be overridden by the compiler at compile-time.
*
* @deprecated - Warns against using the marked function, method, or property should not be used.
*
*- @enum - Specifies the type of an enum. An enum is an object whose properties constitute a
* set of related constants. The @enum tag must be followed by a type expression.
*
* @export - Declares an exported property. Exported properties will have an alias set up so
* they can be accessed via [] syntax.
*
*- @extends - Marks a class or interface as inheriting from another class. A class marked
* with @extends must also be marked with either @constructor or @interface.
*
*- @implements - Used with @constructor to indicate that a class implements an interface.
*
*- @inheritDoc - tag implies the @override tag. has exactly the same documentation.
*
* @interface - Marks a function as an interface.
*
* @lends
*
* @license|@preserve - Tells the compiler to insert the associated comment before the compiled
* code for the marked file.
*
* @nosideeffects - Indicates that a call to the declared function has no side effects
*
*- @override - Indicates that a method or property of a subclass intentionally hides a method or
* property of the superclass.
*
* @param - Used with method, function and constructor definitions to specify the types of function
* arguments.
*
* @private - Marks a member as private. Only code in the same file can access global variables and
* functions marked @private. Constructors marked @private can only be instantiated by code
* in the same file and by their static and instance members.
*
* @protected - Indicates that a member or property is protected.
*
* @return - Specifies the return types of method and function definitions. The @return tag must be
* followed by a type expression.
*
* @this - Specifies the type of the object to which the keyword this refers within a function.
* The @this tag must be followed by a type expression.
*
* @type - Identifies the type of a variable, property, or expression. The @type tag must be
* followed by a type expression.
*
* @typedef - Declares an alias for a more complex type.
*/
void emitConst(IVariableNode node);
void emitExtends(IClassDefinition superDefinition, String packageName);
void emitImplements(ITypeDefinition definition, String packageName);
void emitOverride(IFunctionNode node);
void emitParam(IParameterNode node, String packageName);
void emitPublic(IASNode node);
void emitPrivate(IASNode node);
void emitProtected(IASNode node);
void emitReturn(IFunctionNode node, String packageName);
void emitThis(ITypeDefinition node, String packageName);
void emitType(IASNode node, String packageName);
void emitType(String type, String packageName);
}