abidoc 0.0.1 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e04cd527574913ca48d6b137779994b1b8591e5f6fef541eb15bf8e3b6189b2c
-  data.tar.gz: f7ad37ae9775b095d34f74907fee9b84f6af5e574ff939de34090fe654ce98cf
+  metadata.gz: 63f3e9a48dff69f7a1b40cfdb0576a6780c80a7e789969996a93987263769c8c
+  data.tar.gz: 934f1f64b48b26106b16511f775b7353356128cc6236a9e8cde97747ccb207d7
 SHA512:
-  metadata.gz: 9c60fab097d3b48c02367f98a4f64690c7679467b7c68ab0f7d50631d9da65a75b1546c03cba5644da23fd671643cfef9f9ba8ea89aa832d7926f623495b5aeb
-  data.tar.gz: c9aa02b3c23cc0b0bc147138726f352d70dedb5e9ecd09b6f4e0be479379d61522b5f15af1c3bccbc75d16ed0e36dded8fcc77356499266e1458928d7d234e12
+  metadata.gz: 2cc8363ca326724f2afd6f950f2a4556f8fbff67682f05ddbf400ef5bd3a8cc160e498816483c0b2ffb5115dd3a86c9164009382b8dcb9e36409299623315dda
+  data.tar.gz: c72388140e2e625c264817fafab023a80b5ee4641fa70c1b6285e2149b3bcb1e23cba42593f04a2cdc4542bc8fc169a252964683e7546c3f1df92bf86f283f64

data/Manifest.txt

@@ -3,4 +3,6 @@ Manifest.txt
 README.md
 Rakefile
 lib/abidoc.rb
+lib/abidoc/generate.rb
+lib/abidoc/model.rb
 lib/abidoc/version.rb

data/README.md

@@ -9,9 +9,123 @@ abidoc - application binary interface (abi) documentation generator for Ethereum
 * rdoc  :: [rubydoc.info/gems/abidoc](http://rubydoc.info/gems/abidoc)
 
 
+
 ## Usage
 
 
+Let's try to generate the contract abi docs
+for punks v1 (anno 2017):
+
+``` ruby
+require 'abidoc'
+
+punks_v1    = '0x6ba6f2207e343923ba692e5cae646fb0f566db8d'
+
+abi = ABI.read( "./abis/#{punks_v1}.json" )
+buf = abi.generate_doc( title: 'Contract ABI for Punks V1' )
+write_text( "./o/punks_v1.md", buf )
+```
+
+resulting in:
+
+
+---
+
+# Contract ABI for Punks V1
+
+
+**Constructor**
+
+- constructor()
+
+**1 Payable Function(s)**
+
+- function buyPunk(uint256 punkIndex) _payable_
+
+**7 Transact Functions(s)**
+
+- function reservePunksForOwner(uint256 maxForThisRun)
+- function withdraw()
+- function transferPunk(address to, uint256 punkIndex)
+- function offerPunkForSaleToAddress(uint256 punkIndex, uint256 minSalePriceInWei, address toAddress)
+- function offerPunkForSale(uint256 punkIndex, uint256 minSalePriceInWei)
+- function getPunk(uint256 punkIndex)
+- function punkNoLongerForSale(uint256 punkIndex)
+
+**14 Query Functions(s)**
+
+- function name() ⇒ (string _) _readonly_
+- function punksOfferedForSale(uint256 _) ⇒ (bool isForSale, uint256 punkIndex, address seller, uint256 minValue, address onlySellTo) _readonly_
+- function totalSupply() ⇒ (uint256 _) _readonly_
+- function decimals() ⇒ (uint8 _) _readonly_
+- function imageHash() ⇒ (string _) _readonly_
+- function nextPunkIndexToAssign() ⇒ (uint256 _) _readonly_
+- function punkIndexToAddress(uint256 _) ⇒ (address _) _readonly_
+- function standard() ⇒ (string _) _readonly_
+- function balanceOf(address _) ⇒ (uint256 _) _readonly_
+- function symbol() ⇒ (string _) _readonly_
+- function numberOfPunksToReserve() ⇒ (uint256 _) _readonly_
+- function numberOfPunksReserved() ⇒ (uint256 _) _readonly_
+- function punksRemainingToAssign() ⇒ (uint256 _) _readonly_
+- function pendingWithdrawals(address _) ⇒ (uint256 _) _readonly_
+
+---
+
+
+Let's try to generate the contract abi docs
+for punk blocks (anno 2022):
+
+``` ruby
+punk_blocks = '0x58e90596c2065befd3060767736c829c18f3474c'
+
+abi = ABI.read( "./address/#{punk_blocks}.json" )
+
+buf =  abi.generate_doc( title: 'Contract ABI for Punk Blocks' )
+write_text( "./punk_blocks.md", buf )
+```
+
+resulting in:
+
+---
+
+# Contract ABI for Punk Blocks
+
+
+**Constructor**
+
+- constructor()
+
+**1 Transact Functions(s)**
+
+- function registerBlock(bytes _dataMale, bytes _dataFemale, uint8 _layer, string _name)
+
+**8 Query Functions(s)**
+
+- function blocks(bytes32 _) ⇒ (uint8 layer, bytes dataMale, bytes dataFemale) _readonly_
+- function getBlocks(uint256 _fromID, uint256 _count) ⇒ (tuple[] _, uint256 _) _readonly_
+- function index(uint256 _) ⇒ (bytes32 _) _readonly_
+- function nextId() ⇒ (uint256 _) _readonly_
+- function svgFromIDs(uint256[] _ids) ⇒ (string _) _readonly_
+- function svgFromKeys(bytes32[] _attributeKeys) ⇒ (string _) _readonly_
+- function svgFromNames(string[] _attributeNames) ⇒ (string _) _readonly_
+- function svgFromPunkID(uint256 _tokenID) ⇒ (string _) _readonly_
+
+---
+
+and so on.
+
+
+
+
+## Bonus - Awesome Contracts
+
+See the [**Awesome (Ethereum) Contracts  / Blockchain Services @ Open Blockchains**](https://github.com/openblockchains/awesome-contracts) repo.
+that is a cache of (ethereum) contract ABIs (application binary interfaces)
+and  open source code (if verified / available)
+with auto-generated docs via abidoc & friends.
+
+
+
 
 
 ## License

data/lib/abidoc/generate.rb

@@ -0,0 +1,85 @@
+module ABI
+  class Contract
+
+
+def generate_doc( title: 'Contract ABI',
+                  natspec: nil )
+  buf = ''
+  buf << "# #{title}\n\n"
+
+  if natspec && natspec.head.size > 0
+    natspec.head.each do |line|
+       buf <<  (line.empty? ? "\n" : "#{line}\n")
+    end
+  end
+  buf << "\n\n"
+
+
+  if events.size > 0
+    buf << "\n"
+    buf << "**#{events.size} Event Log Type(s)**\n\n"
+    events.each do |event|
+      buf << "- #{event.doc}\n"
+    end
+  end
+
+
+
+  if @ctor
+    buf << "\n"
+    buf << "**Constructor**\n\n"
+    buf << "- #{@ctor.doc}\n"
+    ## buf << "  - sig #{@ctor.sig}  =>  0x#{sig(@ctor.sig).hexdigest}\n"
+  end
+
+  if payable_functions.size > 0
+    buf << "\n"
+    buf << "**#{payable_functions.size} Payable Function(s)**\n\n"
+    payable_functions.each do |func|
+      buf << "- #{func.doc} _payable_\n"
+      ## buf << "  - sig #{func.sig}  =>  0x#{sig(func.sig).hexdigest}\n"
+    end
+  end
+
+  if transact_functions.size > 0
+    buf << "\n"
+    buf << "**#{transact_functions.size} Transact Functions(s)**\n\n"
+    transact_functions.each do |func|
+      buf << "- #{func.doc}\n"
+      ## buf << "  - sig #{func.sig}  =>  0x#{sig(func.sig).hexdigest}\n"
+    end
+  end
+
+
+  if query_functions.size > 0
+    buf << "\n"
+    buf << "**#{query_functions.size} Query Functions(s)**\n\n"
+    query_functions.each do |func|
+      if natspec && (natspec.storage[ func.name] || natspec.functions[ func.name ])
+        sect = natspec.storage[ func.name ] || natspec.functions[ func.name ]
+        buf << "-  #{sect[0]}"
+        sect[1].each do |line|
+              buf <<  (line.empty? ? " <br>" : " <br> #{line}")
+             end
+        buf << "\n"
+      else
+       buf << "- #{func.doc} _readonly_\n"
+       ## buf << "  - sig #{func.sig}  =>  0x#{sig(func.sig).hexdigest}\n"
+      end
+    end
+  end
+
+  if helper_functions.size > 0
+    buf << "\n"
+    buf << "**#{helper_functions.size} Helper Functions(s)**\n\n"
+    helper_functions.each do |func|
+      buf << "- #{func.doc}\n"
+      ## buf << "  - sig #{func.sig}  =>  0x#{sig(func.sig).hexdigest}\n"
+    end
+  end
+
+  buf
+end
+
+end  ## class Contract
+end ##  module ABI

data/lib/abidoc/model.rb

@@ -0,0 +1,67 @@
+module ABI
+
+class Param
+  def doc
+    buf = ''
+    if @internal_type && @internal_type != sig
+      buf << "#{@internal_type} "
+    else
+      buf << "#{sig} "
+    end
+    buf <<  (@name ?  @name : '_')
+    buf
+  end
+end
+
+
+class Constructor
+  def doc
+    buf = "constructor"
+    if @inputs.empty?
+      buf << "()"
+    else
+      params = @inputs.map {|param| param.doc }
+      buf << "(#{params.join(', ')})"
+    end
+    buf
+  end
+end  ## class Constructor
+
+class Function
+  def doc
+    ## note: text with markdown formatting
+    buf = "function **#{@name}**"
+    if @inputs.empty?
+      buf << "()"
+    else
+      params = @inputs.map {|param| param.doc }
+      buf << "(#{params.join(', ')})"
+    end
+    if @outputs.empty?
+       ## do nothing
+    else
+      buf << " ⇒ "
+      params = @outputs.map {|param| param.doc }
+      buf << "(#{params.join(', ')})"
+    end
+    buf
+  end
+end  ## class Function
+
+
+class Event
+  def doc
+    ## note: text with markdown formatting
+    buf = "event **#{@name}**"
+    if @inputs.empty?
+      buf << "()"
+    else
+      params = @inputs.map {|param| param.doc }
+      buf << "(#{params.join(', ')})"
+    end
+    buf
+  end
+end  ## class Event
+
+
+end  ## module ABI

data/lib/abidoc/version.rb

@@ -2,7 +2,7 @@
 module ABIDoc
 
   MAJOR = 0
-  MINOR = 0
+  MINOR = 1
   PATCH = 1
   VERSION = [MAJOR,MINOR,PATCH].join('.')
 

data/lib/abidoc.rb

@@ -1,64 +1,11 @@
 require 'abiparser'
+require 'natspec'
 
 
 ## our own code
 require_relative 'abidoc/version'    # note: let version always go first
+require_relative 'abidoc/model'
+require_relative 'abidoc/generate'
 
 
 
-module ABI
-  class Contract
-
-
-def generate_doc( title: 'Contract ABI' )
-  buf = ''
-  buf << "# #{title}\n\n"
-
-  if @ctor
-    buf << "\n"
-    buf << "**Constructor**\n\n"
-    buf << "- #{@ctor.doc}\n"
-    ## buf << "  - sig #{@ctor.sig}  =>  0x#{sig(@ctor.sig).hexdigest}\n"
-  end
-
-  if payable_functions.size > 0
-    buf << "\n"
-    buf << "**#{payable_functions.size} Payable Function(s)**\n\n"
-    payable_functions.each do |func|
-      buf << "- #{func.doc} _payable_\n"
-      ## buf << "  - sig #{func.sig}  =>  0x#{sig(func.sig).hexdigest}\n"
-    end
-  end
-
-  if transact_functions.size > 0
-    buf << "\n"
-    buf << "**#{transact_functions.size} Transact Functions(s)**\n\n"
-    transact_functions.each do |func|
-      buf << "- #{func.doc}\n"
-      ## buf << "  - sig #{func.sig}  =>  0x#{sig(func.sig).hexdigest}\n"
-    end
-  end
-
-  if query_functions.size > 0
-    buf << "\n"
-    buf << "**#{query_functions.size} Query Functions(s)**\n\n"
-    query_functions.each do |func|
-      buf << "- #{func.doc} _readonly_\n"
-      ## buf << "  - sig #{func.sig}  =>  0x#{sig(func.sig).hexdigest}\n"
-    end
-  end
-
-  if helper_functions.size > 0
-    buf << "\n"
-    buf << "**#{helper_functions.size} Helper Functions(s)**\n\n"
-    helper_functions.each do |func|
-      buf << "- #{func.doc}\n"
-      ## buf << "  - sig #{func.sig}  =>  0x#{sig(func.sig).hexdigest}\n"
-    end
-  end
-
-  buf
-end
-
-end  ## class Contract
-end ##  module ABI

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: abidoc
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.1
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-12-26 00:00:00.000000000 Z
+date: 2023-02-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: abiparser
@@ -73,6 +73,8 @@ files:
 - README.md
 - Rakefile
 - lib/abidoc.rb
+- lib/abidoc/generate.rb
+- lib/abidoc/model.rb
 - lib/abidoc/version.rb
 homepage: https://github.com/rubycocos/blockchain
 licenses: