Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

please add missing API documentation items #113

Open
KonradHoeffner opened this issue Feb 3, 2023 · 10 comments
Open

please add missing API documentation items #113

KonradHoeffner opened this issue Feb 3, 2023 · 10 comments
Labels
joss Issues related to the JOSS paper submission

Comments

@KonradHoeffner
Copy link

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.
@th5 th5 added the joss Issues related to the JOSS paper submission label Feb 3, 2023
augustearth added a commit that referenced this issue Feb 15, 2023
@augustearth
#113
d0c6339
augustearth added a commit that referenced this issue Mar 2, 2023
@augustearth
#113
244900a
augustearth added a commit that referenced this issue Mar 17, 2023
@augustearth
#113
39afc53
augustearth added a commit that referenced this issue Mar 17, 2023
@augustearth
#113, #115
9b89e6a
augustearth added a commit that referenced this issue Mar 18, 2023
@augustearth
#113
6c699fb
augustearth added a commit that referenced this issue Mar 21, 2023
@augustearth
#113
fe237d8
augustearth added a commit that referenced this issue Mar 29, 2023
@augustearth
#113
5391338
@augustearth
Copy link
Collaborator

Done. Updated documentation are available online.

@KonradHoeffner
Copy link
Author

KonradHoeffner commented Mar 30, 2023 •
edited

Thank you! However I still see undocumented items.

@augustearth
Copy link
Collaborator

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

@KonradHoeffner
Copy link
Author

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
Copy link
Collaborator

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
Copy link
Author

KonradHoeffner commented Mar 31, 2023 •
edited

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
Copy link
Contributor

th5 commented Apr 28, 2023

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

@th5
Copy link
Contributor

th5 commented Apr 28, 2023 •
edited by augustearth

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?

@th5 th5 reopened this Apr 28, 2023
augustearth added a commit that referenced this issue May 11, 2023
@augustearth
#113
4959ad0
@augustearth
Copy link
Collaborator

augustearth commented May 11, 2023 •
edited

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

@hjwilli
Copy link
Collaborator

hjwilli commented May 15, 2023

  • 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
joss Issues related to the JOSS paper submission
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@th5 @KonradHoeffner @hjwilli @augustearth