hq20 / soldoc Goto Github PK

Describe the solution you'd like
Instead of presenting only the methods visibility, show all the modifier for a given function, using badges.

Example https://getbootstrap.com/docs/4.4/components/badge/#contextual-variations

Describe the solution you'd like
Maintaining a UI without much control is becoming harder. And with the new feature requests, it's even more important. After research, it's been decided that using react in HTML would be a good option. Example https://gist.github.com/obernardovieira/6890bdfccf65428fbc7d4a405997360e

Describe the solution you'd like
Most projects, if not all, have tests. Tests also work as documentation. They must be listed has part of the documentation.

Describe the solution you'd like

Something similar to https://fezvrasta.github.io/bootstrap-material-design/docs/4.0/material-design/drawers/ so we can see source code and tests without wasting page's space.

Some people have asciis on their readmes.

                                                  `T",.`-,
                                                     '8, :.
                                              `""`oooob."T,.
                                            ,-`".)O;8:doob.'-.
                                     ,..`'.'' -dP()d8O8Yo8:,..`,
                                   -o8b-     ,..)doOO8:':o; `Y8.`,
                                  ,..bo.,.....)OOO888o' :oO.  ".  `-.
                                , "`"d....88OOOOO8O88o  :O8o;.    ;;,b
                               ,dOOOOO""""""""O88888o:  :O88Oo.;:o888d
                               ""888Ob...,-- :o88O88o:. :o'"""""""Y8OP
                               d8888.....,.. :o8OO888:: ::
                              "" .dOO8bo`'',,;O88O:O8o: ::,
                                 ,dd8".  ,-)do8O8o:"""; :::
                                 ,db(.  T)8P:8o:::::    :::
                                 -"",`(;O"KdOo::        :::
                                   ,K,'".doo:::'        :o:
                                    .doo:::"""::  :.    'o:
        ,..            .;ooooooo..o:"""""     ::;. ::;.  'o.
   ,, "'    ` ..   .d;o:"""'                  ::o:;::o::  :;
   d,         , ..ooo::;                      ::oo:;::o"'.:o
  ,d'.       :OOOOO8Oo::" '.. .               ::o8Ooo:;  ;o:
  'P"   ;  ;.OPd8888O8::;. 'oOoo:.;..         ;:O88Ooo:' O"'
  ,8:   o::oO` 88888OOo:::  o8O8Oo:::;;     ,;:oO88OOo;  '
 ,YP  ,::;:O:  888888o::::  :8888Ooo::::::::::oo888888o;. ,
 ',d: :;;O;:   :888888::o;  :8888888Ooooooooooo88888888Oo; ,
 dPY:  :o8O     YO8888O:O:;  O8888888888OOOO888"" Y8o:O88o; ,
,' O:  'ob`      "8888888Oo;;o8888888888888'"'     `8OO:.`OOb .
'  Y:  ,:o:       `8O88888OOoo"""""""""""'           `OOob`Y8b`
   ::  ';o:        `8O88o:oOoP                        `8Oo `YO.
   `:   Oo:         `888O::oP                          88O  :OY
    :o; 8oP         :888o::P                           do:  8O:
   ,ooO:8O'       ,d8888o:O'                          dOo   ;:.
   ;O8odo'        88888O:o'                          do::  oo.:
  d"`)8O'         "YO88Oo'                          "8O:   o8b'
 ''-'`"            d:O8oK  -hrr-                   dOOo'  :o":
                   O:8o:b.                        :88o:   `8:,
                   `8O:;7b,.                       `"8'     Y:
                    `YO;`8b'
                     `Oo; 8:.
                      `OP"8.`
                       :  Y8P
                       `o  `,
                        Y8bod.
                        `""""'

------------------------------------------------
Thank you for visiting https://asciiart.website/
This ASCII pic can be found at
https://asciiart.website//index.php?art=animals/horses

Describe the solution you'd like
A link to the repository from the documentation. Maybe something like what happens with docsify when adding the git URL.

Request from HQ20/contracts#24

• Version:v8.2.1
• Platform:64-bit (Windows)
• Subsystem:

Documentation generation fails when constructor comments are missing.

In file pdf.js line 55, I had to extend this:

if (contract.contractData.constructor !== null)

To this:

if (contract.contractData.constructor !== null && contract.contractData.constructor.comments !== undefined)

Thanks

Describe the solution you'd like
Would be interesting to ignore specific methods to be rendered. something like

// soldoc-ignore
function some() public pure returns(uint) {
    return 0;
}

We currently have both, as a result of moving to typescript and add tslint but not remove eslint.

On the other hand, tslint will be deprecated, so we need to update eslint. Further information

https://medium.com/palantir/tslint-in-2019-1a144c2317a9
https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/eslint-plugin-tslint

Describe the solution you'd like
It would be cool to have loaded the README.md in the main page (index.html) and maybe other .md's files like CONTRIBUTING.md, LICENSE, and others.

• HTML render contract comment
• parse contract comment

• Version: 0.1.1-beta.2

So that it is clear that is not the main description.

The same that there is a coloured line at the top of each method/event/variable, there should be a ~10px footer in the same colour with the method/event/variable/constructor word within.

Describe the solution you'd like
Right now, only the README.md and LICENSE are copied if they exist. And not across all of the 4 results.

First, it is necessary to have a method that is consistently called, whatever the desired result is.
Second, it is also necessary to look at other standard files, such as

• CONTRIBUTING(.md)?
• CODE_OF_CONDUCT(.md)?
• SECURITY(.md)?

Describe the solution you'd like
If templates come from an external source, then it will allow others to contribute with templates.

BY default, we should have one template.

As of for #32 it's possible to see that solidity-parser-antlr has changed and it needs to be refactored.

Describe the solution you'd like
A new template for the HTML output. Maybe using https://tailwindcss.com/components and following the style. Clean, simple, minimalist.

https://grapesjs.com/demo.html

• HTML render constructor comments
• parse contructor comments

All should be fixed to the proportions below:

The current documentation only shows the members of the contracts themselves. Inherited functionality is an important part of the documentation picture.

Describe the solution you'd like
When coding a big project, there are some interfaces. They are not really necessary sometimes. A flag to avoid them all would be cool.

Check implementation at truffle. It's may speed up generation process.D
Docs reference: https://www.trufflesuite.com/docs/truffle/reference/configuration#solc
Package: https://github.com/trufflesuite/truffle/tree/develop/packages/truffle-compile
I may implement this if needed.

Since the tests do not test the page content, it was not generating proper documentation. There was no information about the parameters.

Describe the solution you'd like
There are too many dependencies in soldoc, currently. First of all, soldoc is meant to be more like a plugin, not a system, so it shouldn't have grab dependencies with it. Some of those dependencies should be in devDependencies.

• Node Version: v12.13.0
• Soldoc Version: v0.1.2-beta.0
• Platform: 16.04.1-Ubuntu x64

params: () => (val, render) => paramComments.get(render(val)),
TypeError: Cannot read property 'get' of undefined

I am getting this error when running soldoc on a particular contract. Strangely, it runs fine on contracts such as Ownable.sol (standard contract) and Migrations.sol (truffle suite).

After some manual debugging it seems to be related to the constructor having arguments. The constructor with arguments is throwing the error shown above.

Describe the solution you'd like
Instead of having different variables, let's have a JSON object

This are missing dependencies required to run

npm install -D puppeteer typescript

Often same contracts (e.g external common deps) needs to be ignored from build process.
.soldocignore may resolve this case as .gitignore for git :)

Current solution e.g
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css"> breaks page loading on local opening (file proto used)

Describe the solution you'd like
Support the new solidity version.

• method
• variable

Describe the solution you'd like
With HQ20/sol-comments-parser#2 it will be possible to render single line comments, as well as #13

Since solidity-parser-antlr parses comments since federicobond/solidity-parser-antlr#71, it would be good to use it instead of sol-comments-parser, having less dependencies and less redundant functionalities.

Sometimes we may not want to get the documentation about a specific file. We need an option to ignore it!

Describe the solution you'd like
Moving to TypeScript

• HTML render event comments
• parse event comments

Add more tests and achieve at least 80% coverage before releasing 0.1.0.

• Version: v0.1.2-beta.1
• Platform: linux mint 19.2
• Subsystem:

.../contracts/node_modules/soldoc/node_modules/solidity-parser-antlr/dist/index.js:79                                                                  
    throw new ParserError({ errors: listener.getErrors() });                                                                                                                                      
    ^                                                                                                                                                                                             
ParserError: no viable alternative at input '/**\n     * @dev All states ever created.\n     */mapping' (29:4)

This happens when doing something similar to

/**
* @notice All roles ever created.
*/
mapping (bytes32 => int) internal someVarName;

Bulma proved to be a good CSS framework. Instead of using built-in styles, let's move to Bulma.