carnival-data/carnival

please add missing API documentation items

Opened this issue · 10 comments

KonradHoeffner commented

This issue is part of the JOSS review.

At https://carnival-data.github.io/carnival/groovydoc/index.html there are still many undocumented items.
Please provide documentation for all items in the API docs.

augustearth commented

Done. Updated documentation are available online.

KonradHoeffner commented

Thank you! However I still see undocumented items.

augustearth commented

Hi @KonradHoeffner. If you let us know the areas you feel are under-documented, we can attempt to address them. Thanks.

KonradHoeffner commented

I mean there are still items that don't have any documentation at all. I have never used Groovy but isn't there some command that lists those items? For example in Rust there is the "missing docs" annotation, so I think this should be possible in other languages as well.

augustearth commented

Hi @KonradHoeffner. I am unaware of a way to tag missing docs in Groovy. The tool used to build Groovy documentation is GroovyDoc, which (I assume) is a layer over JavaDoc. I have gone through our source code and attempted to document all the important classes, fields, and methods. The version of Gradle that is currently used for this project creates docs for protected and private elements. Some of these may not have full documentation, but also would not be expected to be used in client code.

Again, if you let us know know which portions of the API are under-documented, we can attempt to address. Thanks.

KonradHoeffner commented

Unfortunately I don't have the time to manually go through hundreds of documentation items and report which ones exactly are missing but if GroovyDoc is a layer over JavaDoc, maybe it is possible to use Java DocLint.

For example, with JavaDoc, you can use "javadoc -Xdoclint:all ".
Does GroovyDoc have similar functionality?

Public items should be enough, however I am not sure which items are public in the docs as there seems to be no indicator for that.

For example, in https://carnival-data.github.io/carnival/groovydoc/index.html, in
package carnival.core.graph in the interface summary, GraphSchema and GraphValidator are undocumented but that is just one example of many.

th5 commented

Thank you, Konrad. We are almost finished updating the public API documentation.

  • 👍1
th5 commented

To view all items in the API documentation:

https://github.com/carnival-data/carnival
=> click link, under External Resources

GroovyDoc API Documentation
https://carnival-data.github.io/carnival/groovydoc/index.html
=> click link, middle top of page

Index
https://carnival-data.github.io/carnival/groovydoc/index.html?index-all.html

Here is what I found:

These are labelled "do not use". Are we using them internally? Should we make them private?

augustearth commented

4959ad0

  • I have no idea where FilesUtil.1 is coming from. It does not appear in the source. Must be an artifact of compilation?
  • all methods in TinkerpopAnonTraversalExtension have a @see tag
  • MIN_VALUE, MAX_VALUE, valueOf(), values(), previous(), and next() are methods of all enums and should not need commenting
  • there are @see references for CarnivalNeo4jConfiguration
  • 🎉1
hjwilli commented
  • I have no idea where FilesUtil.1 is coming from. It does not appear in the source. Must be an artifact of compilation?

It seems like this is from an anonymous inner class defined here, it should be safe to ignore.