API doc

Author: DarienRaymond

annotations.go

@@ -0,0 +1,14 @@
+package core
+
+// Annotation is a concept in V2Ray. This struct is only for documentation. It is not used anywhere.
+// Annotations begin with "v2ray:" in comment, as metadata of functions or types.
+type Annotation struct {
+	// API is for types or functions that can be used in other libs. Possible values are:
+	//
+	// * v2ray:api:beta for types or functions that are ready for use, but maybe changed in the future.
+	// * v2ray:api:stable for types or functions with guarantee of backward compatibility.
+	// * v2ray:api:deprecated for types or functions that should not be used anymore.
+	//
+	// Types or functions without api annotation should not be used externally.
+	API string
+}

features/dns/client.go

@@ -6,6 +6,8 @@ import (
 )
 
 // Client is a V2Ray feature for querying DNS information.
+//
+// v2ray:api:stable
 type Client interface {
 	features.Feature
 
@@ -14,16 +16,22 @@ type Client interface {
 }
 
 // IPv4Lookup is an optional feature for querying IPv4 addresses only.
+//
+// v2ray:api:beta
 type IPv4Lookup interface {
 	LookupIPv4(domain string) ([]net.IP, error)
 }
 
 // IPv6Lookup is an optional feature for querying IPv6 addresses only.
+//
+// v2ray:api:beta
 type IPv6Lookup interface {
 	LookupIPv6(domain string) ([]net.IP, error)
 }
 
 // ClientType returns the type of Client interface. Can be used for implementing common.HasType.
+//
+// v2ray:api:beta
 func ClientType() interface{} {
 	return (*Client)(nil)
 }

features/inbound/inbound.go

@@ -9,6 +9,8 @@ import (
 )
 
 // Handler is the interface for handlers that process inbound connections.
+//
+// v2ray:api:stable
 type Handler interface {
 	common.Runnable
 	// The tag of this handler.
@@ -19,6 +21,8 @@ type Handler interface {
 }
 
 // Manager is a feature that manages InboundHandlers.
+//
+// v2ray:api:stable
 type Manager interface {
 	features.Feature
 	// GetHandlers returns an InboundHandler for the given tag.
@@ -31,6 +35,8 @@ type Manager interface {
 }
 
 // ManagerType returns the type of Manager interface. Can be used for implementing common.HasType.
+//
+// v2ray:api:stable
 func ManagerType() interface{} {
 	return (*Manager)(nil)
 }

features/outbound/outbound.go

@@ -9,6 +9,8 @@ import (
 )
 
 // Handler is the interface for handlers that process outbound connections.
+//
+// v2ray:api:stable
 type Handler interface {
 	common.Runnable
 	Tag() string
@@ -20,6 +22,8 @@ type HandlerSelector interface {
 }
 
 // Manager is a feature that manages outbound.Handlers.
+//
+// v2ray:api:stable
 type Manager interface {
 	features.Feature
 	// GetHandler returns an outbound.Handler for the given tag.
@@ -34,6 +38,8 @@ type Manager interface {
 }
 
 // ManagerType returns the type of Manager interface. Can be used to implement common.HasType.
+//
+// v2ray:api:stable
 func ManagerType() interface{} {
 	return (*Manager)(nil)
 }

features/policy/policy.go

@@ -57,6 +57,8 @@ type Session struct {
 }
 
 // Manager is a feature that provides Policy for the given user by its id or level.
+//
+// v2ray:api:stable
 type Manager interface {
 	features.Feature
 
@@ -68,6 +70,8 @@ type Manager interface {
 }
 
 // ManagerType returns the type of Manager interface. Can be used to implement common.HasType.
+//
+// v2ray:api:stable
 func ManagerType() interface{} {
 	return (*Manager)(nil)
 }

features/routing/dispatcher.go

@@ -10,6 +10,8 @@ import (
 
 // Dispatcher is a feature that dispatches inbound requests to outbound handlers based on rules.
 // Dispatcher is required to be registered in a V2Ray instance to make V2Ray function properly.
+//
+// v2ray:api:stable
 type Dispatcher interface {
 	features.Feature
 
@@ -18,6 +20,8 @@ type Dispatcher interface {
 }
 
 // DispatcherType returns the type of Dispatcher interface. Can be used to implement common.HasType.
+//
+// v2ray:api:stable
 func DispatcherType() interface{} {
 	return (*Dispatcher)(nil)
 }

features/routing/router.go

@@ -8,6 +8,8 @@ import (
 )
 
 // Router is a feature to choose an outbound tag for the given request.
+//
+// v2ray:api:stable
 type Router interface {
 	features.Feature
 
@@ -16,6 +18,8 @@ type Router interface {
 }
 
 // RouterType return the type of Router interface. Can be used to implement common.HasType.
+//
+// v2ray:api:stable
 func RouterType() interface{} {
 	return (*Router)(nil)
 }

features/stats/stats.go

@@ -5,6 +5,8 @@ package stats
 import "v2ray.com/core/features"
 
 // Counter is the interface for stats counters.
+//
+// v2ray:api:stable
 type Counter interface {
 	// Value is the current value of the counter.
 	Value() int64
@@ -15,6 +17,8 @@ type Counter interface {
 }
 
 // Manager is the interface for stats manager.
+//
+// v2ray:api:stable
 type Manager interface {
 	features.Feature
 
@@ -35,6 +39,8 @@ func GetOrRegisterCounter(m Manager, name string) (Counter, error) {
 }
 
 // ManagerType returns the type of Manager interface. Can be used to implement common.HasType.
+//
+// v2ray:api:stable
 func ManagerType() interface{} {
 	return (*Manager)(nil)
 }

functions.go

@@ -20,6 +20,8 @@ func CreateObject(v *Instance, config interface{}) (interface{}, error) {
 
 // StartInstance starts a new V2Ray instance with given serialized config.
 // By default V2Ray only support config in protobuf format, i.e., configFormat = "protobuf". Caller need to load other packages to add JSON support.
+//
+// v2ray:api:stable
 func StartInstance(configFormat string, configBytes []byte) (*Instance, error) {
 	config, err := LoadConfig(configFormat, "", bytes.NewReader(configBytes))
 	if err != nil {
@@ -39,6 +41,8 @@ func StartInstance(configFormat string, configBytes []byte) (*Instance, error) {
 // It dispatches the request to the given destination by the given V2Ray instance.
 // Since it is under a proxy context, the LocalAddr() and RemoteAddr() in returned net.Conn
 // will not show real addresses being used for communication.
+//
+// v2ray:api:stable
 func Dial(ctx context.Context, v *Instance, dest net.Destination) (net.Conn, error) {
 	dispatcher := v.GetFeature(routing.DispatcherType())
 	if dispatcher == nil {

transport/internet/system_dialer.go

@@ -79,6 +79,8 @@ func (v *SimpleSystemDialer) Dial(ctx context.Context, src net.Address, dest net
 
 // UseAlternativeSystemDialer replaces the current system dialer with a given one.
 // Caller must ensure there is no race condition.
+//
+// v2ray:api:stable
 func UseAlternativeSystemDialer(dialer SystemDialer) {
 	if dialer == nil {
 		effectiveSystemDialer = DefaultSystemDialer{}

v2ray.go

@@ -303,6 +303,8 @@ func (s *Instance) GetFeature(featureType interface{}) features.Feature {
 
 // Start starts the V2Ray instance, including all registered features. When Start returns error, the state of the instance is unknown.
 // A V2Ray instance can be started only once. Upon closing, the instance is not guaranteed to start again.
+//
+// v2ray:api:stable
 func (s *Instance) Start() error {
 	s.access.Lock()
 	defer s.access.Unlock()