search

carnival-data / carnival

JVM property graph data unification framework
https://carnival-data.github.io/carnival/
GNU General Public License v3.0
7 stars 2 forks source link

please add missing API documentation items #113

Open KonradHoeffner opened 1 year ago

KonradHoeffner commented 1 year ago

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 1 year ago

Done. Updated documentation are available online.

KonradHoeffner commented 1 year ago

Thank you! However I still see undocumented items.

augustearth commented 1 year ago

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

KonradHoeffner commented 1 year ago

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 1 year ago

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 1 year ago

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 1 year ago

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

th5 commented 1 year ago

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 1 year ago

4959ad0e7368eff80b4ef80653a027b04e9bc7dc

hjwilli commented 1 year ago
  • 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.