Add built-in function docs #604

DavidKnott · 2017-12-24T03:52:23Z

- What I did

Created a docs page for Vipers built-in functions

- How I did it

Looked over the functions in functions.py and wrote documentation for them.

- How to verify it

Read the documentation

- Description for the changelog

None

- Cute Animal Picture

fordacious · 2017-12-24T04:07:02Z

docs/built-in-functions.rst

+
+Functions
+=========
+The first list dictates each argument and the second sublist lists the types allowed as input.


Maybe consider some simple examples.

In fact linking to the online execution environment (compiler / remix etc...) with executable examples in context would be super useful to developers but that would require writing those examples so should be a separate task

I'm a fan of simple examples, down the road maybe we could have a section in examples/ dedicated to showing off specific viper functionality?

fordacious · 2017-12-24T04:17:28Z

docs/built-in-functions.rst

+    :param a: value to round down
+    :type a: either decimal or num
+
+    :output b: interger


spelling: interger -> integer

fordacious · 2017-12-24T04:20:01Z

docs/built-in-functions.rst

+    :output product: num256[2]
+    """
+
+Takes two elliptical curves and mupltiples them together.


spelling: mupltiples -> multiplies

fordacious · 2017-12-24T04:21:14Z

docs/built-in-functions.rst

+    """
+    :param a: pair to be multipled
+    :type a: num252[2]
+    :param b: pair to be multipled


spelling: multipled -> multiplied

fordacious · 2017-12-24T04:21:25Z

docs/built-in-functions.rst

+
+  def ecadd(a, b) -> product:
+    """
+    :param a: pair to be multipled


spelling: multipled -> multiplied

fordacious · 2017-12-24T04:22:39Z

docs/built-in-functions.rst

+
+Functions
+=========
+The first list dictates each argument and the second sublist lists the types allowed as input.


The type information appears to be available in the signature annotations. Would it be possible to utilize that info?

I just removed this line as I think it just creates more confusion then it's worth.

fordacious · 2017-12-24T04:23:01Z

docs/built-in-functions.rst

+
+  def extract32(a, b, type=c) -> d:
+    """
+    :param a: where 32 bytes are extacted from


spelling: extacted -> extracted

fordacious · 2017-12-24T04:30:02Z

docs/built-in-functions.rst

+    """
+Returns the length of a given list of bytes.
+
+* **concat**


concat appears to lack the signature annotation in functions.py (Is this problematic?)

I don't think it's a problem, it doesn't have signature annotations because it takes a dynamic number of arguments.

Thought that might be the case. On inspection of the code it looks ok, as concat checks its own argument semantics.

fordacious · 2017-12-24T04:36:11Z

docs/built-in-functions.rst

+  def as_num128(a) -> b:
+    """
+    :param a: value to turn into int128
+    :type a: either num, bytes32, num256, or bytes


Consider specific examples as to how this transformation occurs, in order to avoid surprises and sneaky bugs for developers.

fordacious · 2017-12-24T04:39:15Z

docs/built-in-functions.rst

+
+    :output b: bytes
+    """
+**Name:** ``method_id``


fordacious · 2017-12-24T04:42:13Z

docs/built-in-functions.rst

+* **decimal**
+::
+
+  def decimal(a) -> b:


Name is different from other type conversion functions. Is this an intensional design choice?

Also it doesn't seem to be included in the types.rst conversion table.

We might want to change the name to as_decimal

fordacious · 2017-12-24T04:46:40Z

docs/built-in-functions.rst

+    :param a: value to turn into decimal
+    :type a: either decimal or num
+
+    :output b: decimal


For these type conversions we should be sure to document general behavior and corner cases (e.g. underflow / overflow behavior)

fordacious · 2017-12-24T04:52:46Z

docs/built-in-functions.rst

+
+    :output d: bytes
+    """
+Takes a a list of bytes, the start bytes to take and the length to take and returns the associated chunk.


Copied or referenced? (Possible source of sneaky bugs)

fordacious · 2017-12-24T04:55:53Z

docs/built-in-functions.rst

+* **concat**
+::
+
+  def concat(a, b, ...) -> c:


Missing documentation of variadic args here (...). We should document constraints here (e.g. concat requires two or more arguments of type byte32 or byte[])

fordacious · 2017-12-24T05:04:12Z

docs/built-in-functions.rst

+  def bytes_to_num(a) -> b:
+    """
+    :param a: bytes to be transformed
+    :type a: bytes


Consider documenting the behavior when arrays are length 0 if that is valid input

fordacious · 2017-12-24T05:06:22Z

docs/built-in-functions.rst

+* **slice**
+::
+
+  def slice(a, start=b, length=c) -> d:


consider documenting the behavior when the range is invalid for the given input

sdtsui

Nice work, @fordacious!

sdtsui · 2017-12-24T06:53:19Z

docs/built-in-functions.rst

+
+    :output d: bytes
+    """
+Takes a a list of bytes, the start bytes to take and the length to take and returns the associated chunk.


typo:

Takes a a list of bytes

sdtsui · 2017-12-24T06:54:29Z

docs/built-in-functions.rst

+    """
+
+Takes a function declaration and returns its method_id (used in data field to call it).
+


Sometimes there are two spaces between annotations, other times there are one. Intentional?

DavidKnott · 2017-12-25T08:18:23Z

@fordacious @sdtsui Thanks a lot for the feedback, I corrected the typos and tried to make a few parts clearer. Merging this in.

fordacious mentioned this pull request Dec 24, 2017

extract32 #597

Closed

fordacious reviewed Dec 24, 2017

View reviewed changes

DavidKnott force-pushed the add-functions-docs branch from 1a2fa0d to 077aa82 Compare December 24, 2017 05:38

sdtsui reviewed Dec 24, 2017

View reviewed changes

DavidKnott force-pushed the add-functions-docs branch from 077aa82 to 3c354b0 Compare December 25, 2017 04:03

Add built-in function docs

9a218f7

DavidKnott force-pushed the add-functions-docs branch from 3c354b0 to 9a218f7 Compare December 25, 2017 04:19

DavidKnott merged commit eb4b1dd into vyperlang:master Dec 25, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add built-in function docs #604

Add built-in function docs #604

DavidKnott commented Dec 24, 2017

fordacious Dec 24, 2017

fordacious Dec 24, 2017

DavidKnott Dec 24, 2017

fordacious Dec 24, 2017

fordacious Dec 24, 2017

fordacious Dec 24, 2017

fordacious Dec 24, 2017

fordacious Dec 24, 2017

DavidKnott Dec 24, 2017

fordacious Dec 24, 2017

fordacious Dec 24, 2017 •

edited

Loading

DavidKnott Dec 24, 2017

fordacious Dec 24, 2017

fordacious Dec 24, 2017

fordacious Dec 24, 2017

fordacious Dec 24, 2017

fordacious Dec 24, 2017

DavidKnott Dec 25, 2017

fordacious Dec 24, 2017

fordacious Dec 24, 2017

fordacious Dec 24, 2017

fordacious Dec 24, 2017

fordacious Dec 24, 2017

sdtsui left a comment

sdtsui Dec 24, 2017

sdtsui Dec 24, 2017

DavidKnott commented Dec 25, 2017

		"""

		Takes a function declaration and returns its method_id (used in data field to call it).

Add built-in function docs #604

Add built-in function docs #604

Conversation

DavidKnott commented Dec 24, 2017

- What I did

- How I did it

- How to verify it

- Description for the changelog

- Cute Animal Picture

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fordacious Dec 24, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sdtsui left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DavidKnott commented Dec 25, 2017

fordacious Dec 24, 2017 •

edited

Loading