Allow natspec documentation for non-public functions.

[androlo]

Issue created on @chriseth 's request.

The proposal is to allow contract writers to document non-public functions using natspec, and that those docs are included in the json output.

Additionally, there could be a compiler flag to ignore non-public function docs (which may or may not be enabled by default).

[chriseth]

This is basically about changing the loops in Natspec.cpp to go over all functions, and not just over the interfaceFunctions.

[chriseth]

The problem is that we might not have an externalSignature in all cases. Because of that, we might want to split up the externalSignature function in one that assumes a library and one that does not.

[VarunWachaspati]

Interested to take this up, complete newbie so might take sometime to actually figure it out though
Let me know if it's fine

[chriseth]

@VarunWachaspati wonderful! Yes, this is not urgent, but please keep us posted.

[VarunWachaspati]

@chriseth Surely will do so. Kindly assign this issue to me.
Also let me know any resources/documentation that I should be referring for the issue.

[androlo]

I want to do this as well. Potentially i could also develop natspec further after this issue is done, if the proposed issues are accepted. For example.

1. Return is a single string instead of having one per output param, like input. That can be updated.
2. Documentation for modifiers, constants and events could be added (internal constants for the same reason as internal functions).
3. Could be more docs for contracts/libraries, and the author tag could be extended.
4. Would be nice if there was a way to reference other docs - especially when extending other contracts/implementing interfaces. Maybe it could be implemented in the form of json pointers.

Eventually, function docs could have a more rich format where they can be formalized to some extent. Even though why3 support is gone, perhaps there could be something like a very simple assertion language that could be read and evaluated (maybe through Z3). Of course that would be in the future.

[chriseth]

@VarunWachaspati sorry, I cannot assign this to you because you are not part of the project, but please feel free to work on it.

@androlo I think there are separate issues for most of the items you mention. An important aspect of natspec adoption is also to get it into further tools. Mist, metamask, etherscan, etc. should display them and also use the templating language. Perhaps you could connect to the relevant people and ask/help them implement it?

[androlo]

@chriseth ok.

[androlo]

i can hear what they think and then write up a number suggestions that seems to be popular. maybe check with the research/formal people as well (other then you i mean). I could start poking around after devcon, and see if it's possible to make a concerted effort.

[chriseth]

I don't think we will get very far with formalizing semantics, we tried that using why3 and failed due to various reasons. The plan is now to replace that with the much easier to use require/assert mechanism.

[androlo]

ok, no problems. The focus will be mainly to see if existing docs and tags can be improved, then see what happens.

[androlo]

Some questions about getting a list of functions.

The ContractDefinition::interfaceFunctionList function gathers all interface functions into a vector of (hashed signature, function type pointer) pairs. It will filter out functions that are already registered, by using the external signature as the unique identifier.

Maybe have one function ContractDefinition::functionList which gathers all functions into a vector of (external signature, function type pointer) pairs, which could be used to get all functions. ContractDefinition::interfaceFunctionList could just filter that vector to get the interface functions, but that would of course require an additional pass.

Otherwise there could just be something in natspec to get functions through ContractDefinition::definedFunctions and work from that.

Wat do.

[androlo]

Edit AST.h/cpp feels too intrusive, but maybe complete function list is useful for other things. Happy to just build docs from natspec.cpp, and create any utility functions there as needed.

[github-actions]

This issue has been marked as stale due to inactivity for the last 90 days.
It will be automatically closed in 7 days.

[cameel]

This seems to be already implemented.

Also, even if it weren't, we already have another issue covering this: #12295.