Can the template handle @!group and @!endgroup directives ?

[DanRathbun]

Can the template handle @!group and @!endgroup directives, reading them in stubs, pulling them into C++, and then output again to stubs, html ?

One of the files needing update is "_top_level.rb" and the constants need to be grouped into a collapsing section.

Did you get a chance to try the "dcutils.rb" file I had sent (in "Group.zip.txt") or just view the "Group.html" file in that zip ? https://github.com/SketchUp/ruby-api-docs/issues/38#issuecomment-272575411

[thomthom]

Never used the @group tag. I need to look closer at what they do. But from the sound of it I wonder if they can solve some of the issues I had in trying to get constants to stay grouped in the stubs.

Does that default YARD template support that tag?

(I've not had a chance to look at the dcutils.rb file. Very busy days when I'm here at Boulder so my time I very limited for the duration of this month.)

[thomthom]

Just noticed this PR in the YARD repo: "Enable groups for constants" https://github.com/lsegal/yard/pull/1056

Would that affect this topic?

[DanRathbun]

@thomthom

Never used the @!group tag. I need to look closer at what they do.

They currently work for grouping methods into separate summary groups at the top of the class pages. (So far I've been unable to get them to also group some descriptive text along inside the group.)

Does that default YARD template support that tag?

Yes, and again, I gave you an example of both the input "dcutils.rb" and the output "Group.html" from the "default" YARD template, in the zip attached to the referenced comment (above) in Issue 38.

I wonder if they can solve some of the issues I had in trying to get constants to stay grouped in the stubs.

I'll need to try this locally for constants first.

Just noticed this PR (lsegal/yard#1056) in the YARD repo: "Enable groups for constants" Would that affect this topic?

It might, ... I'll look into this.

---

But my concern (and the question here) is with your "round trip" tools. Can your diff tool "see" @group & @endgroup tags, roll them back into C++ comments ? Afterward YARD should be able to output them back into the stubs if your stubs template has not suppressed them ? Likewise your YARD HTML output template should have no problem creating the groups sections.

So the first thing for YOU to try locally, is that special "dcutils.rb" which groups methods (which do work with groups,) just to test the "round trip".

[thomthom]

Currently the tool isn't doing anything with @group tags. I need to dig into that to see exactly how it works. My gut feeling is that it won't work right now, but maybe something we can hook up.

[DanRathbun]

@thomthom: Just noticed this PR in the YARD repo: "Enable groups for constants" lsegal/yard#1056 Would that affect this topic?

Okay, yes this is the basic feature I have always wanted re, Constants. That they are by default listed in a collapsible group just like the methods. (Not sure why this was not done from the start?)

Then after this, it would be nice to be able to subgroup them into collapsible sublists with headings.

I've subscribed to that YARD PR to see when it is merged.

[DanRathbun]

Okay, I confirm the current YARD "default" template will not honor @!group directives, for grouping constants. We'll need to watch that feature PR in the YARD repo.

[DanRathbun]

Never used the @!group tag. I need to look closer at what they do.

Here is a very good example of separating methods into categorical summary groups. (Note that they are still listed in alpha order in the method details litings.)

http://www.rubydoc.info/gems/yard/0.9.5/YARD/Templates/Helpers/HtmlHelper

[DanRathbun]

Looks like there is movement on the constant grouping PR in the YARD repo ...

[DanRathbun]

@thomthom Loren Segal has merged the constant grouping PR into master, but not since released a new YARD version.