Refactor code to prepare for security audit

[maraoz]

No description provided.

[Qkyrie]

any todo's that can be picked up here?

[maraoz]

I don't have any concrete tasks to list, my plan was to traverse the whole codebase and check that code style is good, and easy to understand. If you read our code audits you'll see I mention a lot of advice to make the auditor's life easier. If you're interested, feel free to read them and apply similar ideas to Zeppelin:

• https://medium.com/zeppelin-blog/ethercamps-projectkudos-public-code-audit-179ee0c6672d#.2r909r9rz
• https://medium.com/zeppelin-blog/golem-network-token-gnt-audit-edfa4a45bc32#.fdb6kf20d
• https://medium.com/zeppelin-blog/arcade-city-arc-token-audit-9071fa55a4e8#.w2hm1kqpe
• https://medium.com/zeppelin-blog/ethercamps-hacker-gold-hkg-public-code-audit-b7dd3a2fe43b#.lilgtncq9
• https://medium.com/zeppelin-blog/onward-with-ethereum-smart-contract-security-97a827e47702#.6gku925cm

[Qkyrie]

Will definitely do!

[veox]

Any thoughts on making documentation with Doxygen, instead of the current Sphinx? In particular, Solidity docs mention Doxygen-like comments, as does this wiki page about NSF.

Making documentation inline with code could improve general doc quality, or at least highlight what's missing. This could make an auditor's life easier, and maybe a general user's, too.

This would mean switching doc-gen machinery, though, which will complicate things for the project maintainers. Sphinx can't directly handle non-Python code with Doxygen-style comments AFAIK, but it can use an extension, breathe, to generate from Doxygen-produced XML, like described in this SO answer. That would mean having two doc-gen systems instead of one, though.

[veox]

OTOH, it may be simpler to extract Doxygen-style comment lines from .sol files, format them a bit, and dump to respective .rst files for Sphinx to handle. Essentially the same as now, but scripted instead of manual.

[maraoz]

@veox I like that idea

[veox]

Heh, which one?

I've accidentally started working on the latter, here's WIP so far. (It's pretty ugly, and misses much of what makes a language.)

(EDIT: Just noticed breathe is available on RTD.io. The above wasn't necessary.)

What this increasingly looks like would be much better instead of "dumping" it straight into doc/source, though, is a custom Sphinx domain for Solidity.

There turns out to be a Sphinx extension for this, too - domaintools. Using that, however, would probably require modifications to the doc-building machine. It seems this is possible with readthedocs.

[veox]

To clarify, there is still need to extract the natspec before passing to Sphinx. A custom Sphinx domain is not strictly necessary - something similar, like Javascript, could probably be used.

[maraoz]

@veox The latter :) would you like to open a new issue for that? I'm closing this issue based on work on this PR: #146