Skip to content

Commit e0a8028

Browse files
duncanpoduncanpo
committed
Add help text
1 parent 38752a7 commit e0a8028

32 files changed

+457
-51
lines changed

‎api/baggage/+opentelemetry/+baggage/+propagation/BaggagePropagator.m

+6
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,12 @@
55

66
methods
77
function obj = BaggagePropagator()
8+
% Propagator for injecting and extracting baggage from HTTP header
9+
% PROP = OPENTELEMETRY.BAGGAGE.PROPAGATION.BAGGAGEPROPAGATOR
10+
% creates a baggage propagator.
11+
%
12+
% See also
13+
% OPENTELEMETRY.TRACE.PROPAGATION.TRACECONTEXTPROPAGATOR
814
proxy = libmexclass.proxy.Proxy("Name", ...
915
"libmexclass.opentelemetry.BaggagePropagatorProxy", ...
1016
"ConstructorArguments", {});

‎api/baggage/+opentelemetry/+baggage/Baggage.m

+35-3
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,26 @@
44
% Copyright 2023 The MathWorks, Inc.
55

66
properties (Dependent)
7-
Entries (1,1) dictionary
7+
Entries (1,1) dictionary % Name-value pairs stored in baggage
88
end
99

1010
properties (Access=private)
11-
Proxy
11+
Proxy % Proxy object to interface C++ code
1212
end
1313

1414
methods
1515
function obj = Baggage(entries)
16+
% Object that stores name-value pairs, to be passed along in a context
17+
% B = OPENTELEMETRY.BAGGAGE.BAGGAGE creates an empty baggage
18+
% object.
19+
%
20+
% B = OPENTELEMETRY.BAGGAGE.BAGGAGE(ENTRIES) populate
21+
% baggage with the name-value pairs stored in dictionary
22+
% ENTRIES. The keys and values in ENTRIES must both be
23+
% strings.
24+
%
25+
% See also
26+
% OPENTELEMETRY.BAGGAGE.PROPAGATION.BAGGAGEPROPAGATOR
1627
if nargin < 1
1728
entries = dictionary(strings(0,1),strings(0,1));
1829
end
@@ -25,7 +36,7 @@
2536
else % input is baggage entries
2637
if isa(entries, "dictionary")
2738
[keytype, valuetype] = types(entries);
28-
% baggage keys and values must be strings
39+
% baggage keys and values must be strings
2940
if keytype == "string" && valuetype == "string"
3041
obj.Proxy = libmexclass.proxy.Proxy("Name", ...
3142
"libmexclass.opentelemetry.BaggageProxy", ...
@@ -66,6 +77,13 @@
6677
end
6778

6879
function obj = setEntries(obj, keys, values)
80+
% SETENTRIES Set entry values
81+
% B = SETENTRIES(B, KEYS, VALUES) sets the values associated
82+
% with keys KEYS. Both KEYS and VALUES must be string arrays
83+
% or cell array of character vectors of the same length. If
84+
% a key is not in baggage B, the key will be added.
85+
%
86+
% See also DELETEENTRIES
6987
arguments
7088
obj
7189
keys {mustBeVector, mustBeText}
@@ -78,6 +96,12 @@
7896
end
7997

8098
function obj = deleteEntries(obj, keys)
99+
% DELETEENTRIES Delete entries from baggage
100+
% B = DELETEENTRIES(B, KEYS) delete the entries associated
101+
% with keys KEYS. If a key is not in baggage B, it will be
102+
% ignored.
103+
%
104+
% See also SETENTRIES
81105
arguments
82106
obj
83107
keys {mustBeVector, mustBeText}
@@ -86,6 +110,14 @@
86110
end
87111

88112
function context = insertBaggage(obj, context)
113+
% INSERTBAGGAGE Insert baggage into a context
114+
% NEWCTXT = INSERTBAGGAGE(B) inserts baggage B into the
115+
% current context and returns a new context NEWCTXT.
116+
%
117+
% NEWCTXT = INSERTBAGGAGE(B, CTXT) specifies the context to
118+
% insert into.
119+
%
120+
% See also OPENTELEMETRY.BAGGAGE.CONTEXT.EXTRACTBAGGAGE
89121
if nargin < 2
90122
context = opentelemetry.context.getCurrentContext();
91123
end

‎api/baggage/+opentelemetry/+baggage/Context.m

+11-2
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,25 @@
44
% Copyright 2023 The MathWorks, Inc.
55

66
methods (Static)
7-
% extract baggage from context
87
function bg = extractBaggage(context)
8+
% Extract baggage from context
9+
% B = OPENTELEMETRY.BAGGAGE.CONTEXT.EXTRACTBAGGAGE(CTXT)
10+
% extracts baggage from context CTXT.
11+
%
12+
% See also OPENTELEMETRY.BAGGAGE.CONTEXT.INSERTBAGGAGE
913
arguments
1014
context (1,1) opentelemetry.context.Context
1115
end
1216
bg = opentelemetry.baggage.Baggage(context);
1317
end
1418

15-
% insert baggage into context and return new context
1619
function context = insertBaggage(context, baggage)
20+
% Insert baggage into context
21+
% NEWCTXT = OPENTELEMETRY.BAGGAGE.CONTEXT.INSERTBAGGAGE(CTXT, B)
22+
% inserts baggage B into context CTXT, and returns a new
23+
% context.
24+
%
25+
% See also OPENTELEMETRY.BAGGAGE.CONTEXT.EXTRACTBAGGAGE
1726
arguments
1827
context (1,1) opentelemetry.context.Context
1928
baggage (1,1) opentelemetry.baggage.Baggage

‎api/context/+opentelemetry/+context/+propagation/CompositePropagator.m

+9
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,15 @@
55

66
methods
77
function obj = CompositePropagator(propagator)
8+
% Composite propagator composed of multiple propagators
9+
% CPROP =
10+
% OPENTELEMETRY.CONTEXT.PROPAGATION.COMPOSITEPROPAGATOR(PROP1,
11+
% PROP2, ...) creates a composite propagator CPROP that is
12+
% composed of multiple propagators PROP1, PROP2, ...
13+
%
14+
% See also
15+
% OPENTELEMETRY.TRACE.PROPAGATION.TRACECONTEXTPROPAGATOR,
16+
% OPENTELEMETRY.BAGGAGE.PROPAGATION.BAGGAGEPROPAGATOR
817
arguments (Repeating)
918
propagator (1,1) {mustBeA(propagator, ...
1019
["opentelemetry.trace.propagation.TraceContextPropagator", ...

‎api/context/+opentelemetry/+context/+propagation/Propagator.m

+13
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,23 @@
55

66
methods (Static)
77
function p = getTextMapPropagator()
8+
% Get the global instance of text map propagator
9+
% PROP =
10+
% OPENTELEMETRY.CONTEXT.PROPAGATION.PROPAGATOR.GETTEXTMAPPROPAGATOR
11+
% returns the global instance of text map propagator.
12+
%
13+
% See also
14+
% OPENTELEMETRY.CONTEXT.PROPAGATION.PROPAGATOR.SETTEXTMAPPROPAGATOR
815
p = opentelemetry.context.propagation.TextMapPropagator();
916
end
1017

1118
function setTextMapPropagator(p)
19+
% Set the global instance of text map propagator
20+
% OPENTELEMETRY.CONTEXT.PROPAGATION.PROPAGATOR.SETTEXTMAPPROPAGATOR(PROP)
21+
% sets text map propagator PROP as the global instance.
22+
%
23+
% See also
24+
% OPENTELEMETRY.CONTEXT.PROPAGATION.PROPAGATOR.GETTEXTMAPPROPAGATOR
1225
p.setTextMapPropagator();
1326
end
1427
end

‎api/context/+opentelemetry/+context/+propagation/TextMapCarrier.m

+15-3
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,31 @@
11
classdef TextMapCarrier
2-
% Carrier that stores key-value pairs, used for injecting to and extracting
2+
% Carrier that stores name-value pairs, used for injecting into and extracting
33
% from HTTP headers
44

55
% Copyright 2023 The MathWorks, Inc.
66

77
properties (Access=?opentelemetry.context.propagation.TextMapPropagator)
8-
Proxy
8+
Proxy % Proxy object to interface C++ code
99
end
1010

1111
properties (Dependent, SetAccess=private)
12-
Headers
12+
Headers % Name-value pairs either extracted from or to be injected into an HTTP header
1313
end
1414

1515
methods
1616
function obj = TextMapCarrier(in)
17+
% Name-value pair carrier, used for injecting into and extracting from HTTP headers.
18+
% C = OPENTELEMETRY.CONTEXT.PROPAGATION.TEXTMAPCARRIER
19+
% creates and empty carrier.
20+
%
21+
% C = OPENTELEMETRY.CONTEXT.PROPAGATION.TEXTMAPCARRIER(HEADER)
22+
% populates the carrier with name-value pairs stored in HTTP
23+
% header. HEADER must be a Nx2 string array or cell array of
24+
% character vectors.
25+
%
26+
% See also
27+
% OPENTELEMETRY.TRACE.PROPAGATION.TRACECONTEXTPROPAGATOR,
28+
% OPENTELEMETRY.BAGGAGE.PROPAGATION.BAGGAGEPROPAGATOR
1729
if nargin < 1
1830
in = strings(0,2);
1931
end

‎api/context/+opentelemetry/+context/+propagation/TextMapPropagator.m

+20-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
% Copyright 2023 The MathWorks, Inc.
55

66
properties (Access=?opentelemetry.context.propagation.CompositePropagator)
7-
Proxy
7+
Proxy % Proxy object to interface C++ code
88
end
99

1010
methods (Access={?opentelemetry.context.propagation.Propagator, ...
@@ -24,6 +24,13 @@
2424

2525
methods
2626
function newcontext = extract(obj, carrier, context)
27+
% EXTRACT Extract HTTP header from carrier into a context.
28+
% NEWCTXT = EXTRACT(PROP, C, CTXT) extracts HTTP header
29+
% stored in carrier C into context CTXT, and returns a new
30+
% context NEWCTXT.
31+
%
32+
% See also INJECT, OPENTELEMETRY.CONTEXT.CONTEXT,
33+
% OPENTELEMETRY.CONTEXT.PROPAGATION.TEXTMAPCARRIER
2734
if nargin < 3
2835
context = opentelemetry.context.getCurrentContext();
2936
end
@@ -34,6 +41,12 @@
3441
end
3542

3643
function newcarrier = inject(obj, carrier, context)
44+
% INJECT Inject HTTP header from a context into a carrier.
45+
% C = INJECT(PROP, C, CTXT) injects HTTP header in context
46+
% CTXT into carrier C.
47+
%
48+
% See also EXTRACT, OPENTELEMETRY.CONTEXT.CONTEXT,
49+
% OPENTELEMETRY.CONTEXT.PROPAGATION.TEXTMAPCARRIER
3750
if nargin < 3
3851
context = opentelemetry.context.getCurrentContext();
3952
end
@@ -44,6 +57,12 @@
4457
end
4558

4659
function setTextMapPropagator(obj)
60+
% SETTEXTMAPPROPAGATOR Set propagator as the global instance.
61+
% SETTEXTMAPPROPAGATOR(PROP) sets the propagator PROP as the
62+
% global instance.
63+
%
64+
% See also
65+
% OPENTELEMETRY.CONTEXT.PROPAGATION.PROPAGATOR.GETTEXTMAPPROPAGATOR
4766
obj.Proxy.setTextMapPropagator();
4867
end
4968
end

‎api/context/+opentelemetry/+context/+propagation/extractContext.m

+6-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
function newcontext = extractContext(carrier)
2-
% Extract context data from TextMapCarrier
2+
% Extract HTTP header from TextMapCarrier
3+
% NEWCTXT = OPENTELEMETRY.CONTEXT.PROPAGATION.EXTRACTCONTEXT(C) uses the
4+
% global instance of text map propagator to extract HTTP header from
5+
% carrier C into the current context and returns a new context.
6+
%
7+
% See also OPENTELEMETRY.CONTEXT.PROPAGATION.INJECTCONTEXT
38

49
% Copyright 2023 The MathWorks, Inc.
510

‎api/context/+opentelemetry/+context/+propagation/injectContext.m

+6-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
function carrier = injectContext(carrier)
2-
% Inject context data into a TextMapCarrier
2+
% Inject HTTP header into a TextMapCarrier
3+
% C = OPENTELEMETRY.CONTEXT.PROPAGATION.INJECTCONTEXT(C) uses the
4+
% global instance of text map propagator to inject HTTP header from
5+
% the current context into carrier C.
6+
%
7+
% See also OPENTELEMETRY.CONTEXT.PROPAGATION.EXTRACTCONTEXT
38

49
% Copyright 2023 The MathWorks, Inc.
510

‎api/context/+opentelemetry/+context/Context.m

+12-3
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,20 @@
11
classdef Context
2-
% Context class used to store context information including the current
3-
% span and baggage
2+
% Propagation mechanism used to carry context data across functions and
3+
% external interfaces.
44

55
% Copyright 2023 The MathWorks, Inc.
66

77
properties (Access={?opentelemetry.context.propagation.TextMapPropagator, ...
88
?opentelemetry.trace.Span, ?opentelemetry.trace.Tracer, ...
99
?opentelemetry.baggage.Baggage})
10-
Proxy
10+
Proxy % Proxy object to interface C++ code
1111
end
1212

1313
methods
1414
function obj = Context(proxy)
15+
% Propagation mechanism used to carry context data across functions and external interfaces.
16+
% CTXT = OPENTELEMETRY.CONTEXT.CONTEXT creates an empty
17+
% context object.
1518
if nargin < 1
1619
obj.Proxy = libmexclass.proxy.Proxy("Name", ...
1720
"libmexclass.opentelemetry.ContextProxy", ...
@@ -22,6 +25,12 @@
2225
end
2326

2427
function token = setCurrentContext(obj)
28+
% SETCURRENTCONTEXT Set context to be current context.
29+
% TOKEN = SETCURRENTCONTEXT(CTXT) sets context to be current
30+
% context and returns a token object which determines the duration
31+
% when CTXT is current. When TOKEN is deleted, CTXT will no longer be current.
32+
%
33+
% See also OPENTELEMETRY.CONTEXT.TOKEN
2534
tokenid = obj.Proxy.setCurrentContext();
2635
tokenproxy = libmexclass.proxy.Proxy("Name", ...
2736
"libmexclass.opentelemetry.TokenProxy", "ID", tokenid);

‎api/context/+opentelemetry/+context/Token.m

+3-2
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
classdef Token < handle
2-
% Token object that controls the duration when a context is current
2+
% Token object that controls the duration when a context is current. Upon
3+
% deletion, the associated context will no longer be current.
34

45
% Copyright 2023 The MathWorks, Inc.
56

67
properties (Access=private)
7-
Proxy
8+
Proxy % Proxy object to interface C++ code
89
end
910

1011
methods (Access=?opentelemetry.context.Context)

‎api/context/+opentelemetry/+context/getCurrentContext.m

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
function context = getCurrentContext()
2-
% Get the current context object
2+
% Get the current context object.
3+
% CTXT = OPENTELEMETRY.CONTEXT.GETCURRENTCONTEXT returns the current
4+
% context object.
35

46
% Copyright 2023 The MathWorks, Inc.
57

‎api/trace/+opentelemetry/+trace/+propagation/TraceContextPropagator.m

+7
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,13 @@
55

66
methods
77
function obj = TraceContextPropagator()
8+
% Propagator for injecting and extracting trace context from HTTP headers.
9+
% PROP = OPENTELEMETRY.TRACE.PROPAGATION.TRACECONTEXTPROPAGATOR
10+
% creates a propagator that can be used for injecting or
11+
% extracting trace context from HTTP headers.
12+
%
13+
% See also
14+
% OPENTELEMETRY.BAGGAGE.PROPAGATION.BAGGAGEPROPAGATOR
815
proxy = libmexclass.proxy.Proxy("Name", ...
916
"libmexclass.opentelemetry.TraceContextPropagatorProxy", ...
1017
"ConstructorArguments", {});

‎api/trace/+opentelemetry/+trace/Context.m

+13-2
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,27 @@
44
% Copyright 2023 The MathWorks, Inc.
55

66
methods (Static)
7-
% extract span from context
87
function sp = extractSpan(context)
8+
% Extract span from context
9+
% SP = OPENTELEMETRY.TRACE.CONTEXT.EXTRACTSPAN(CTXT) extracts
10+
% span SP from a context object CTXT. SP is a nonrecording span
11+
% such that ISRECORDING(SP) returns false. If CTXT does not
12+
% contain any spans, SP will be an invalid span with all-zero
13+
% trace and span IDs.
14+
%
15+
% See also INSERTSPAN, OPENTELEMETRY.CONTEXT.CONTEXT
916
arguments
1017
context (1,1) opentelemetry.context.Context
1118
end
1219
sp = opentelemetry.trace.Span(context);
1320
end
1421

15-
% insert a span into context and return new context
1622
function context = insertSpan(context, span)
23+
% Insert span into context
24+
% NEWCTXT = OPENTELEMETRY.TRACE.CONTEXT.INSERTSPAN(CTXT, SP) inserts
25+
% span SP into a context object CTXT and returns a new context.
26+
%
27+
% See also EXTRACTSPAN, OPENTELEMETRY.CONTEXT.CONTEXT
1728
arguments
1829
context (1,1) opentelemetry.context.Context
1930
span (1,1) opentelemetry.trace.Span

0 commit comments

Comments
 (0)