Paul, thanks a lot for a quick reply!
> On 4. 2. 2025, at 23:59, Paul King <pa...@asert.com.au> wrote: > Groovydoc is widely used but could certainly do with some TLC. All of > Groovy's API documentation for Groovy classes is produced using it. Well, yes, if you don't have sources at hand (which one usually does not with Groovy itself, at least, not one who works on the Groovy like you do :)), then even the list of methods with arguments without a bit of other information helps. Nevertheless, I'd like to have the docs mostly for my own quick-check of APIs of my own projects, especially those written 10+ years ago and forgotten meantime :) In this case non-documented methods are just a hindrance, for in that case it's really better to have a look into the sources. > Wrt to "non-documented" methods should be hidden. Currently it follows > Javadocs behavior where you can turn on/off methods by visibility... Well yes, I've found that much. But for one, private can't be used much in Groovy due to the well-known closure problem <https://lists.apache.org/thread/wvbp4zgjomowynjy5g7kzwk7kvfmpz12>. As for protected I've found it occasionally to clash with ASTTs — my own ones combined with system ones, the problem almost surely would be at my side; but since in Groovy protected rarely (if ever) functionally differs from (implicit) public, I just don't use it. I guess I probably could use protected simply to “hide” methods which I don't want to have documented, but given the size of my projects, it would be lots of work to add it to all those methods, constructors, fields, you-name-them, whose documentation I do not need. It would make much better sense to simply just add documentation to the considerably smaller number of items which I want to see in the docset :) Of course, I have no idea how difficult it would be to add such a feature to groovydoc and whether worth it. My feeling is that it should be pretty easy, but I can be completely wrong, for I haven't checked groovydoc sources. > ... I'd create a distinct feature request > email/issue if you want some other behavior. What's the best way? Should I write a feature request e-mail here, or to the dev list, or would it be better to add a FR jira ticket? > Wrt to the package thing. I have only seen that when the declared > package didn't match the actual folder hierarchy of the source files. That would be culprit. Myself I've never seen any point in the folder hierarchy matching packages and in my projects, they almost never do. (I was just delighted when I found Groovy allows me to define as many classes as I like in any source, completely regardless of the source placement. If only it would allow me to split a definition of one class into more sources, I'd be completely happy :) Traits alas don't help due to diverse limitations of which the incompatibility with ASTTs is probably the worst one, the problems with statics almost as bad.) Of course without checking the groovydoc sources I can't be sure, but would it be that difficult just ignore the folder hierarchy and trust the package declarations inside? > ... best to raise an issue with a replicator Sorry you lost me here. With whom? > and we can try to sort out what is going on. Great, thanks a lot! And I haste to add the priority of all these requests is pretty low :) OC > On Wed, Feb 5, 2025 at 6:03 AM OCsite <o...@ocs.cz> wrote: >> >> Hi there, >> >> I've tried to use groovydoc, and at the first look, it does not seem to work >> quite well. Does anyone really use the thing? >> >> For one, it seems to ignore packages completely — although each of my >> classes contain the “package” line all right, the generated documentation >> shows “Default Package” only; the particular classes are also presented >> without a package. >> >> Even worse is that the generated documentation contains unneeded information >> for all the small supporting methods which have no documentation comments >> and thus should not be shown at all. The result is terribly cluttered and >> good for nothing; the non-documented methods should be hidden. >> >> I must be missing something of importance. I've checked the groovydoc >> options, and it seems there is no package-related option at all (but for >> -exclude, which is not what I need here), and I can't find a switch to skip >> undocumented methods either :( >> >> What do I overlook? >> >> Thanks, >> OC
