Skip to content

Commit 34d2013

Browse files
author
runrevali
committed
[[ StdMlc ]] Update inline docs
1 parent 06b2726 commit 34d2013

File tree

6 files changed

+97
-42
lines changed

6 files changed

+97
-42
lines changed

‎libscript/src/array.mlc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,7 @@ end syntax
219219

220220
/*
221221

222-
Summary: Designates the array with zero elements
222+
Summary: Designates the array with no elements.
223223

224224
Example:
225225
variable tVar as array
@@ -299,7 +299,7 @@ Example:
299299
Description:
300300
Use repeat for each key to iterate over the keys of an array in no particular order.
301301

302-
Tags: Arrays
302+
Tags: Arrays, Control structures
303303
*/
304304

305305
syntax RepeatForEachKey is iterator

‎libscript/src/binary.mlc‎

Lines changed: 50 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -24,13 +24,11 @@ Summary: Prepends <Source> bytes to <Target> bytes.
2424

2525
Source: An expression which evaluates to binary data.
2626
Target: An expression which evaluates to a binary container.
27-
28-
Example:
29-
variable tData as data
30-
variable tPrefixData as data
31-
...
32-
put tPrefixData before tData
3327

28+
Description:
29+
Use to insert bytes into data without replacement. Can be used either with a chunk expression to insert at a specified location, or without to prepend to the target data.
30+
31+
Tags: Binary
3432
*/
3533

3634
syntax PutBytesBefore is statement
@@ -45,9 +43,12 @@ Summary: Appends <Source> bytes to <Target> bytes.
4543
Source: An expression which evaluates to binary data.
4644
Target: An expression which evaluates to a binary container.
4745

48-
Example: put tSuffixData after tData
49-
5046
Related: PutBytesAfter
47+
48+
Description:
49+
Use to insert bytes into data without replacement. Can be used either with a chunk expression to insert at a specified location, or without to append to the target data.
50+
51+
Tags: Binary
5152
*/
5253

5354
syntax PutBytesAfter is statement
@@ -66,7 +67,10 @@ Right: An expression which evaluates to binary data.
6667

6768
Returns: Binary data consisting of the value of the left hand expression with the value of the right hand expression appended to the end.
6869

69-
Example: put tLeft & tRight into tConcatenated
70+
Description:
71+
The result consists of the bytes of <Left> followed by those of <Right>.
72+
73+
Tags: Binary
7074
*/
7175

7276
syntax ConcatenateBytes is left binary operator with precedence 2
@@ -83,9 +87,12 @@ Summary: Determines whether <Left> and <Right> are equal or not.
8387
Left: An expression which evaluates to binary data.
8488
Right: An expression which evaluates to binary data.
8589

86-
8790
Returns: Returns true if the result of evaluating <Left> is the same as that of <Right>, and false otherwise.
8891

92+
Description:
93+
Performs a byte by byte comparison of <Left> and <Right>, returning false if there is any difference.
94+
95+
Tags: Binary
8996
*/
9097

9198
syntax DataIsData is neutral binary operator with precedence 5
@@ -100,9 +107,12 @@ Summary: Determines whether <Left> and <Right> are equal or not.
100107
Left: An expression which evaluates to binary data.
101108
Right: An expression which evaluates to binary data.
102109

103-
104110
Returns: Returns false if the result of evaluating <Left> is the same as that of <Right>, and true otherwise.
105111

112+
Description:
113+
Performs a byte by byte comparison of <Left> and <Right>, returning true if there is any difference.
114+
115+
Tags: Binary
106116
*/
107117

108118
syntax DataIsNotData is neutral binary operator with precedence 5
@@ -118,8 +128,12 @@ Left: An expression which evaluates to binary data.
118128
Right: An expression which evaluates to binary data.
119129

120130

121-
Returns: Returns true if <Left> and <Right> are not equal, and the first byte in <Right> that is not equal to the
122-
corresponding byte in <Left> is of greater value.
131+
Returns: True if <Left> is less than <Right>, and false otherwise.
132+
133+
Description:
134+
<Left> is less than <Right> if they are not equal, and the first byte in <Right> that is not equal to the corresponding byte in <Left> is of greater value.
135+
136+
Tags: Binary
123137
*/
124138

125139
syntax DataIsLessThanData is neutral binary operator with precedence 3
@@ -135,8 +149,12 @@ Left: An expression which evaluates to binary data.
135149
Right: An expression which evaluates to binary data.
136150

137151

138-
Returns: Returns true if <Left> and <Right> are not equal, and the first byte in <Left> that is not equal to the
139-
corresponding byte in <Right> is of greater value.
152+
Returns: True if <Left> is greater than <Right>, and false otherwise.
153+
154+
Description:
155+
<Left> is greater than <Right> if they are not equal, and the first byte in <Left> that is not equal to the corresponding byte in <Right> is of greater value.
156+
157+
Tags: Binary
140158
*/
141159

142160
syntax DataIsGreaterThanData is neutral binary operator with precedence 3
@@ -147,6 +165,23 @@ end syntax
147165

148166
--
149167

168+
/*
169+
170+
Summary: Designates data of length 0.
171+
172+
Example:
173+
variable tVar as data
174+
variable tCount as number
175+
put the empty data into tVar
176+
put the number of bytes in tVar into tCount -- tCount is 0
177+
178+
Description:
179+
Use ```the empty data``` to initialise a data variable.
180+
181+
Tags: Binary
182+
183+
*/
184+
150185
syntax EmptyData is expression
151186
"the" "empty" "data"
152187
begin

‎libscript/src/byte.mlc‎

Lines changed: 37 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -31,11 +31,11 @@ Summary: Counts the number of bytes in <Target>.
3131

3232
Target: An expression which evaluates to binary data.
3333

34-
Example:
34+
Returns: The number of bytes in <Target>
3535

36-
repeat with x = 1 to the number of bytes in tData
37-
// do something
38-
end repeat
36+
Description:
37+
38+
Tags: Binary
3939
*/
4040

4141
syntax CountBytesOf is prefix operator with precedence 1
@@ -53,11 +53,12 @@ Summary: Finds the first or last occurrence of <Needle> within <Targe
5353
Needle: An expression which evaluates to binary data.
5454
Target: An expression which evaluates to binary data.
5555

56-
Returns: Returns the offset of <Needle> in <Target>.
56+
Returns: Returns the offset of <Needle> in <Target>.
5757

5858
Description:
5959
The first (respectively last) offset of <Needle> in <Target> is number of bytes between the first byte of <Target> and the first (respectively last) occurrence of <Needle>. If neither first or last is specified, then the first offset is found. If <Needle> does not occur in <Target>, then the output is 0.
6060

61+
Tags: Binary
6162
*/
6263

6364
syntax ByteOffset is prefix operator with precedence 1
@@ -74,10 +75,12 @@ Needle: An expression which evaluates to binary data.
7475
Target: An expression which evaluates to binary data.
7576
After: An expression which evaluates to a valid integer index of Target.
7677

77-
Returns: Returns the offset of <Needle> after index <After> in <Target>.
78+
Returns: Returns the offset of <Needle> after index <After> in <Target>.
7879

7980
Description:
8081
The first (respectively last) offset of <Needle> in <Target> is number of bytes between byte <After> of <Target> and the first (respectively last) occurrence of <Needle> after <After>. If neither first or last is specified, then the first offset is found. If <Needle> does not occur after <After> in <Target>, then the output is 0.
82+
83+
Tags: Binary
8184
*/
8285

8386
syntax ByteOffsetAfter is prefix operator with precedence 1
@@ -94,11 +97,12 @@ Needle: An expression which evaluates to binary data.
9497
Target: An expression which evaluates to binary data.
9598
After: An expression which evaluates to a valid integer index of Target.
9699

97-
Returns: Returns the offset of <Needle> before index <Before> in <Target>.
100+
Returns: Returns the offset of <Needle> before index <Before> in <Target>.
98101

99102
Description:
100103
The first (respectively last) offset of <Needle> in <Target> is number of bytes between the first byte of <Target> and the first (respectively last) occurrence of <Needle> before <Before>. If neither first or last is specified, then the last offset is found. If <Needle> does not occur before <Before> in <Target>, then the output is 0.
101104

105+
Tags: Binary
102106
*/
103107

104108
syntax ByteOffsetBefore is prefix operator with precedence 1
@@ -112,10 +116,12 @@ Summary: Determines whether <Needle> is in <Target>.
112116
Needle: An expression which evaluates to a single byte of binary data.
113117
Target: An expression which evaluates to binary data.
114118

115-
Returns: True if <Needle> is among the bytes of <Target>, and false otherwise.
119+
Returns: True if <Needle> is among the bytes of <Target>, and false otherwise.
116120

117121
Description:
118122
>*Note:* It is an error if <Needle> evaluates to data consisting of more than one byte.
123+
124+
Tags: Binary
119125
*/
120126

121127
syntax IsAmongTheBytesOf is neutral binary operator with precedence 1
@@ -131,10 +137,12 @@ Summary: Determines whether <Needle> contains <Target>.
131137
Needle: An expression which evaluates to binary data.
132138
Target: An expression which evaluates to binary data.
133139

134-
Returns: True if the bytes of <Needle> occur as a subsequence of the bytes of <Target>, and false otherwise.
140+
Returns: True if the bytes of <Needle> occur as a subsequence of the bytes of <Target>, and false otherwise.
135141

136142
Description:
137143
>*Note:* Since the empty data is a subsequence of every sequence of bytes, every sequence of bytes contains the empty data.
144+
145+
Tags: Binary
138146
*/
139147

140148
syntax ContainsBytes is neutral binary operator with precedence 1
@@ -148,10 +156,12 @@ Summary: Determines whether <Target> begins with <Needle>.
148156
Needle: An expression which evaluates to binary data.
149157
Target: An expression which evaluates to binary data.
150158

151-
Returns: True if the bytes of <Needle> occur as an initial subsequence of the bytes of <Target>, and false otherwise.
159+
Returns: True if the bytes of <Needle> occur as an initial subsequence of the bytes of <Target>, and false otherwise.
152160

153161
Description:
154162
>*Note:* Since the empty data is an initial subsequence of every sequence of bytes, every sequence of bytes begins with the empty data.
163+
164+
Tags: Binary
155165
*/
156166

157167
syntax BeginsWithBytes is neutral binary operator with precedence 1
@@ -165,10 +175,12 @@ Summary: Determines whether <Target> ends with <Needle>.
165175
Needle: An expression which evaluates to binary data.
166176
Target: An expression which evaluates to binary data.
167177

168-
Returns: True if the bytes of <Needle> occur as a final subsequence of the bytes of <Target>, and false otherwise.
178+
Returns: True if the bytes of <Needle> occur as a final subsequence of the bytes of <Target>, and false otherwise.
169179

170180
Description:
171181
>*Note:* Since the empty data is a final subsequence of every sequence of bytes, every sequence of bytes ends with the empty data.
182+
183+
Tags: Binary
172184
*/
173185

174186
syntax EndsWithBytes is neutral binary operator with precedence 1
@@ -185,13 +197,12 @@ Summary: Designates the byte of data at index <Index> in <Target>.
185197
Index: An expression which evaluates to a valid integer index of <Target>.
186198
Target: An expression which evaluates to binary data.
187199

188-
Example: put the empty data into byte 5 of tData // Locates byte 5 and removes it from tData
189-
Example: get byte 5 of tData // Evaluates byte 5
190-
191200
Description:
192201
Either locates the byte at the given index for use as the target container of another operation, or evaluates the byte at the given index as the source of another operation.
193202

194203
>*Note:* It is an error if <Index> is out of range.
204+
205+
Tags: Binary
195206
*/
196207

197208
syntax SingletonByteOf is prefix operator with precedence 1
@@ -208,14 +219,13 @@ Summary: Designates the bytes of data between indices <Start> and <Fi
208219
Start: An expression which evaluates to a valid integer index of <Target>.
209220
Finish: An expression which evaluates to a valid integer index of <Target>.
210221
Target: An expression which evaluates to binary data.
211-
212-
Example: put tBytes into byte 5 to 10 of tData // Locates bytes 5 to 10 and replace them with tBytes
213-
Example: get byte 5 to 10 of tData // Evaluates bytes 5 to 10
214222

215223
Description:
216224
Either locates the bytes between the given indices for use as the target container of another operation, or evaluates the bytes at the given indices as the source of another operation.
217225

218226
>*Note:* It is an error if either <Start> or <Finish> are out of range.
227+
228+
Tags: Binary
219229
*/
220230

221231
syntax RangeByteOf is prefix operator with precedence 1
@@ -225,6 +235,16 @@ begin
225235
MCByteStoreByteRangeOf(input, Start, Finish, Target)
226236
end syntax
227237

238+
/*
239+
Summary: Repeat over the bytes of some data
240+
Iterand: An expression of the form 'tVar in tData'
241+
242+
Description:
243+
Use repeat for each to perform an operation on each byte of some data.
244+
245+
Tags: Binary, Control structures
246+
*/
247+
228248
syntax RepeatForEachByte is iterator
229249
"byte" <Iterand: Expression>
230250
begin

‎libscript/src/char.mlc‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ Summary: Counts the number of chars in <Target>.
3535

3636
Target: An expression which evaluates to a string.
3737

38-
Returns: The number of chars in <Target>.
38+
Returns: The number of chars in <Target>.
3939

4040
Example:
4141

@@ -340,8 +340,8 @@ begin
340340
end syntax
341341

342342
/*
343-
Summary: Repeat over the elements of a list
344-
Iterand: An expression of the form 'tVar in tList'
343+
Summary: Repeat over the chars of a string
344+
Iterand: An expression of the form 'tChar in tString'
345345

346346
Example:
347347
variable tString as string
@@ -357,7 +357,7 @@ Example:
357357
// tReversed is "desserts"
358358

359359
Description:
360-
The repeat for each form is more efficient that the alternative formation using repeat **tCount** times.
360+
Use repeat for each to perform an operation on each char of a string.
361361

362362
Tags: Strings, Control structures
363363
*/

‎libscript/src/list.mlc‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -650,7 +650,7 @@ end syntax
650650

651651
/*
652652

653-
Summary: Designates the list of zero elements
653+
Summary: Designates the list of length zero.
654654

655655
Example:
656656
variable tVar as list
@@ -690,9 +690,9 @@ Example:
690690
// tRelist is the same as tList
691691

692692
Description:
693-
The repeat for each form is more efficient that the alternative formation using repeat **tCount** times.
693+
Use repeat for each to perform an operation on each element of a list.
694694

695-
Tags: Lists
695+
Tags: Lists, Control structures
696696
*/
697697

698698
syntax RepeatForEachElementOfList is iterator

‎libscript/src/string.mlc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -290,7 +290,7 @@ end syntax
290290

291291
/*
292292

293-
Summary: Designates the string consisting of zero chars
293+
Summary: Designates the string of length zero.
294294

295295
Example:
296296
variable tVar as string

0 commit comments

Comments
 (0)