Utility for generating 'providers.md'

[panilya]

At that moment, it doesn't support the descriptions. I will add later

[codecov-commenter]

Codecov Report

Merging #297 (4ca502d) into master (87a721b) will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master     #297   +/-   ##
=========================================
  Coverage     94.86%   94.86%           
- Complexity     1893     1894    +1     
=========================================
  Files           197      197           
  Lines          3797     3797           
  Branches        379      379           
=========================================
  Hits           3602     3602           
  Misses           99       99           
  Partials         96       96           

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[bodiam]

That looks very interesting. Nice work, this would be really nice to have to update the documentation with!

[panilya]

How about introducing a file with descriptions of providers providers_description.yml, and getting descriptions of providers from that file when generating providers' docs with ProvidersDocsGenerator?

[snuyanzin]

Why can't it be done in same javadoc with something like {@description your description here} ?

[panilya]

yes, your idea is better

[panilya]

Writing description in { } inlines description with @since tag in the same line, so it looks kind of unreadable. Do you know to fix it?

[snuyanzin]

Didn't get what you mean.... could you elaborate please?

I mean something like this

/**
 * @since 0.8.0
 * {@description your
 * multiline
 * description
 * }
 */

[panilya]

I mean this:

But if this doesn't matter, I will implement this. I apologize for the lack of clarity.

[bodiam]

No, ideally don't do that (introducing a new file or that syntax with @description.

The javadoc as-is is fine imo, please just use that, and don't introduce something special for this, unless there's a really good reason for that, which at the moment I don't see.

[panilya]

everything looks good to me, what do you think? I think it's ready for merge

[snuyanzin]

Regexp does not work properly
to check run and have a look at record with CPF, column since.
To fix it regexp should be changed to something like "@since\\s+\\d\\.\\d+\\.\\d"
and net.datafaker.script.ProvidersDocsGenerator#matchSinceTag
to

  private String matchSinceTag(String javaDocComment) {
        Matcher comment = pattern.matcher(javaDocComment);

        if (comment.find()) {
            return comment.group().substring("@since".length()).trim();
        }
        return "";
    }

[snuyanzin]

ok from my point of view it looks more or less ok
there are 2 tiny things

1. Probably src/test/java/net/datafaker/script/providers.md should be changed to more suitable location
2. May be it makes sense to make build failing when fakersWithoutSinceTag is not empty however it could be done within a different issue

@bodiam do you have anything to add?

[bodiam]

I'm following it from the side lines, but I think you've covered everything. I don't mind the output location that much, but I think something in the target directory is probably better, or, if you're feeling confident, just overwrite the actual page in the docs.

[bodiam]

I'm thinking of making a new release, is there anything open on this PR?

[panilya]

@bodiam Currently, this utility doesn't include descriptions as in the original one (CNPFJ, CPF, and Mountains), so you need manually copy them. And, because of that, it's not recommended to rewrite the original providers.md. If @snuyanzin doesn't have any ideas or suggestions, you can merge this PR

[bodiam]

@panilya Awesome, I'll fix that. The code is a bit strange at some places, for example the extractTagFromJavadoc. You might think it extracts tags from Javadoc, but it's doesn't. It actually returns comments, and not only that, it also keeps track of files which didn't have a @since field. Also, it doesn't extract things from JavaDoc, it reads files. So, this method should actually be called:

extractJavaodcFromSourceFileAndKeepTrackOfFilesWhichDontHaveASinceField

which is a bit of a mouth full. So, instead, it would probably be better to give this method task: either extract comments form the Javadoc, or keep track of files which don't have a @since field, but not both.

There's really no need to change this, I really appreciate your work on this, but it's just some feedback for in the future, and part of SOLID/SRP(Single Responsibility Pattern), which might be good reading material if you feel like it.