Documentation updates for internal constructors and function signature #3365

elenadimitrova · 2017-12-31T14:37:50Z

Closes #3131
Closes #3132
Closes #627

axic · 2018-01-03T16:04:27Z

docs/contracts.rst

+Constructor functions can be either ``public`` or ``internal``.
+
+::
+


verison pragma is missing here

@axic for the version pragma, do we specify the minimum version required to run the sample or simply the current version, i.e. 0.4.19?

So far the rule has been the minimum required by the example.

The release notes aren't very clear on when this was introduced but Remix thinks this breaks from 0.4.10 downwards so I'll use pragma min 0.4.11 in the example.
From release notes on 0.4.11:

Type system: Contract inheriting from base with unimplemented constructor should be abstract.

axic · 2018-01-03T16:04:36Z

docs/contracts.rst

+::
+
+    contract A {
+    uint public a;


Identation is off here

axic · 2018-01-04T00:46:44Z

docs/contracts.rst

+        function B() public {}
+    }
+
+A constructor set as ``internal`` causes the contract to be marked as :ref:`abstract <abstract-contract>`. Child contracts of an abstract contract can call the super constructor.


Perhaps I'd extend this to say that when extending a contract the parent constructor is called implicitly an as such it is possible that a child contract inheriting an internal constructor from the parent makes it non-abstract. (Would need to phrase this in a more readable form.)

Then as a second feature to that of course one can call the super constructor even if it is marked internal.

Since this is specific to the description of an abstract contracts I think I'll add it to that section if you don't mind.

@axic I don't get what you mean here:

child contract inheriting an internal constructor from the parent makes it non-abstract

A child contract inherits an abstract contract with internal constructor does not become non-abstract necessarily as if for instance it doesn't implement all of the abstract functions, it will be abstract.

axic · 2018-02-12T09:21:52Z

docs/contracts.rst

+Abstractions
+************
+
+An abstraction type describes a contract but does not provide a full implementation of the contract. An abstraction is implemented as abstract contract or interface.


Not sure what "abstraction type" means here.

I see where the confusion comes from, since there's no actual abstract type in Solidity it's probably best to rename "abstraction type" to just "abstraction"

axic · 2018-02-12T09:23:06Z

docs/abi-spec.rst

@@ -26,6 +26,10 @@ The first four bytes of the call data for a function call specifies the function
 first (left, high-order in big-endian) four bytes of the Keccak (SHA-3) hash of the signature of the function. The signature is defined as the canonical expression of the basic prototype, i.e.
 the function name with the parenthesised list of parameter types. Parameter types are split by a single comma - no spaces are used.

+.. note::
+    Return type of the function is not taken into account. In :ref:`function overloading <overload-function>` return types are not considered. The reason is to keep function call resolution context-independent.


I'd clarify the link as "In Solidity's function overloading". The ABI documentation is not Solidity specific, we have just "hijacked it" and imported into our documentation :)

chriseth · 2018-02-12T09:23:38Z

docs/contracts.rst

+.. _abstractions:
+
+************
+Abstractions


Does this section introduce this term? If yes, is it intended to capture both abstract base contracts and interfaces? I'm not sure we should do this as it might be too easily confused with "abstract contract". I would say an interface is a special kind of abstract base contract.

Yes @chriseth see the PR description for motivation.

Also I'm not sure I understand the difference you're drawing between an "abstract contract" and an "abstract base contract", can you explain? An abstract contract cannot be instantiated and therefore makes no sense unless it's a base contract too.

Not sure we need this section in its current form.

How about having a title like "Special contracts" / "Special contract kinds" / "Special contract types" (or something better you can come up with)?

It would only need a sentence stating that some contracts cannot be compiled, but can be used as bases for other contracts.

Maybe the common section was not a good idea after all so I've dropped it

chriseth · 2018-02-12T09:26:37Z

docs/contracts.rst

@@ -1051,13 +1086,13 @@ but they can be used as base contracts::
        function utterance() public returns (bytes32) { return "miaow"; }
    }

+Abstract contracts can implement most of a contract, but leave some methods abstract, facilitating patterns like template method and removing code duplication.


Could you explain what the template method is?
Also, to remove code duplication, it is not required to use an abstract contract, a base contract is enough.

Wikipedia does a good job of explaining the template method, we've used wiki sources before so I assume it's ok to reference that instead of try to redefine it? https://en.wikipedia.org/wiki/Template_method_pattern

axic · 2018-02-26T23:44:08Z

docs/contracts.rst

@@ -1051,13 +1086,13 @@ but they can be used as base contracts::
        function utterance() public returns (bytes32) { return "miaow"; }
    }

+Abstract contracts can implement most of a contract, but leave some methods abstract, facilitating patterns like `Template method <https://en.wikipedia.org/wiki/Template_method_pattern>`_ and removing code duplication.


Perhaps "leave some methods unimplemented" is less confusing since there is no way to mark a method "abstract".

chriseth · 2018-03-01T11:10:47Z

docs/abi-spec.rst

@@ -26,6 +26,10 @@ The first four bytes of the call data for a function call specifies the function
 first (left, high-order in big-endian) four bytes of the Keccak (SHA-3) hash of the signature of the function. The signature is defined as the canonical expression of the basic prototype, i.e.
 the function name with the parenthesised list of parameter types. Parameter types are split by a single comma - no spaces are used.

+.. note::
+    Return type of the function is not taken into account. In :ref:`Solidity's function overloading <overload-function>` return types are not considered. The reason is to keep function call resolution context-independent.


Perhaps The return type of a function is not part of this signature.

chriseth · 2018-03-01T11:11:15Z

docs/contracts.rst

+
+Constructors
+============
+Constructor is an optional function with the same name as the contract which is executed upon contract creation. 


Perhaps: A constructor is an optional...

chriseth · 2018-03-01T11:11:53Z

docs/contracts.rst

@@ -1065,6 +1090,8 @@ Example of a Function Type (a variable declaration, where the variable is of typ

    function(address) external returns (address) foo;

+Abstract contracts allow you to decouple contract definition from implementation providing better extensibility and self-documentation and 


Perhaps decouple the definition of a contract from its implementation?

chriseth · 2018-03-01T11:12:03Z

docs/contracts.rst

@@ -1065,6 +1090,8 @@ Example of a Function Type (a variable declaration, where the variable is of typ

    function(address) external returns (address) foo;

+Abstract contracts allow you to decouple contract definition from implementation providing better extensibility and self-documentation and 
+facilitating patterns like `Template method <https://en.wikipedia.org/wiki/Template_method_pattern>`_ and removing code duplication.


the Template method?

chriseth

Sorry that this pull request took so long. If you do the final small changes, we can merge it.

elenadimitrova · 2018-03-01T11:46:39Z

np @chriseth I understand you're busy. Changes done and rebased

LianaHus added the needs review label Dec 31, 2017

elenadimitrova changed the title ~~Add a note explaining return values not included in function signature~~ Documentation updates for internal constructors and function signature Jan 2, 2018

elenadimitrova force-pushed the documentation/627-3132-abstract-contracts branch 2 times, most recently from 97fd996 to c008403 Compare January 3, 2018 15:19

axic reviewed Jan 3, 2018

View reviewed changes

docs/contracts.rst Outdated

::

contract A {

uint public a;

Copy link

Member

axic Jan 3, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Identation is off here

elenadimitrova reacted with thumbs up emoji

elenadimitrova force-pushed the documentation/627-3132-abstract-contracts branch from c008403 to 6cfbdec Compare January 3, 2018 17:11

axic reviewed Jan 4, 2018

View reviewed changes

elenadimitrova force-pushed the documentation/627-3132-abstract-contracts branch 3 times, most recently from 502bc38 to c8342df Compare January 9, 2018 11:42

elenadimitrova force-pushed the documentation/627-3132-abstract-contracts branch from c8342df to 1541d1d Compare January 15, 2018 16:02

axic reviewed Feb 12, 2018

View reviewed changes

chriseth reviewed Feb 12, 2018

View reviewed changes

elenadimitrova force-pushed the documentation/627-3132-abstract-contracts branch 3 times, most recently from d265047 to cb23a2a Compare February 13, 2018 09:59

axic added the documentation 📖 label Feb 14, 2018

axic reviewed Feb 26, 2018

View reviewed changes

elenadimitrova force-pushed the documentation/627-3132-abstract-contracts branch 2 times, most recently from 9069be2 to eee50c2 Compare February 28, 2018 06:41

chriseth reviewed Mar 1, 2018

View reviewed changes

elenadimitrova added 2 commits March 1, 2018 13:43

Add a note explaining return values not included in function signature

f6ae1f3

Add section on Constructors in documentation

c9bb3db

elenadimitrova added 2 commits March 1, 2018 13:43

Improve documented definition for abstract contract

445720b

Add benefits of abstraction to documentation

4531a97

elenadimitrova force-pushed the documentation/627-3132-abstract-contracts branch from eee50c2 to 4531a97 Compare March 1, 2018 11:46

chriseth approved these changes Mar 1, 2018

View reviewed changes

chriseth merged commit c9840c9 into ethereum:develop Mar 1, 2018

axic mentioned this pull request Apr 17, 2018

Recommend we add a better explanation for abstract contracts #898

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation updates for internal constructors and function signature #3365

Documentation updates for internal constructors and function signature #3365

elenadimitrova commented Dec 31, 2017 •

edited

Loading

axic Jan 3, 2018

elenadimitrova Jan 3, 2018

axic Jan 4, 2018

elenadimitrova Jan 9, 2018

axic Jan 3, 2018

axic Jan 4, 2018

elenadimitrova Jan 9, 2018

elenadimitrova Jan 9, 2018 •

edited

Loading

axic Feb 12, 2018

elenadimitrova Feb 13, 2018

axic Feb 12, 2018

chriseth Feb 12, 2018

elenadimitrova Feb 13, 2018

elenadimitrova Feb 13, 2018

axic Feb 26, 2018

elenadimitrova Feb 28, 2018

chriseth Feb 12, 2018

elenadimitrova Feb 13, 2018

axic Feb 26, 2018

chriseth Mar 1, 2018

chriseth Mar 1, 2018

chriseth Mar 1, 2018

chriseth Mar 1, 2018

chriseth left a comment

elenadimitrova commented Mar 1, 2018

		Constructor functions can be either ``public`` or ``internal``.

		::

		@@ -1065,6 +1090,8 @@ Example of a Function Type (a variable declaration, where the variable is of typ

		function(address) external returns (address) foo;

		Abstract contracts allow you to decouple contract definition from implementation providing better extensibility and self-documentation and

Documentation updates for internal constructors and function signature #3365

Documentation updates for internal constructors and function signature #3365

Conversation

elenadimitrova commented Dec 31, 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

elenadimitrova Jan 9, 2018 • 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chriseth left a comment

Choose a reason for hiding this comment

elenadimitrova commented Mar 1, 2018

elenadimitrova commented Dec 31, 2017 •

edited

Loading

elenadimitrova Jan 9, 2018 •

edited

Loading