-
Notifications
You must be signed in to change notification settings - Fork 413
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.
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
[#1400] Group global constants and functions by file name #1401
base: master
Are you sure you want to change the base?
Conversation
@@ -69,7 +69,42 @@ def self.group_custom_categories(docs, doc_index) | |||
children.each.with_index { |child, i| child.nav_order = i } | |||
make_group(children, category['name'], '') | |||
end | |||
[group.compact, docs] | |||
|
|||
globals_grouped_by_file = self.group_globals_by_file(docs, doc_index) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi @johnfairh, should I place this under a new command line argument or something?
You recommended including a glob/wildcard/regexp
, could you please elaborate a little more on what such a regexp would be used to filtered? Would it be used to determine whether constants in a file should be affected by this logic or not?
I can make that change in a following commit.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The 'glob' comment was in response to your example of "children": [file:GlobalUtils.h"
which is not the feature you ended up going for.
The default behaviour mustn't change because of existing users, new behaviour can be behind a CLI option.
[group.compact, docs] | ||
|
||
globals_grouped_by_file = self.group_globals_by_file(docs, doc_index) | ||
[group.compact, docs + globals_grouped_by_file] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Adding globals_grouped_by_file
to the end of docs makes the Constants
and Functions
sections show up at the end of other default sections, and also prevents the other default groups from being prepended with "Other".
The order of the sections, and file level groups in them appears to be consistent to be. Is there a specific way to ensure order is maintained that you would recommend?
I could sort the files in each group, and symbols in each file alphabetically to be sure. Should I?
cc: @johnfairh
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You need to go back to group_docs()
and figure out the code there -- the advice to start in this routine was based (again :-)) on your other design.
Ruby hash iteration order is guaranteed - I think that is all you need to prove that you don't need any further sorting.
4a12435
to
e7470bb
Compare
@@ -69,7 +69,42 @@ def self.group_custom_categories(docs, doc_index) | |||
children.each.with_index { |child, i| child.nav_order = i } | |||
make_group(children, category['name'], '') | |||
end | |||
[group.compact, docs] | |||
|
|||
globals_grouped_by_file = self.group_globals_by_file(docs, doc_index) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The 'glob' comment was in response to your example of "children": [file:GlobalUtils.h"
which is not the feature you ended up going for.
The default behaviour mustn't change because of existing users, new behaviour can be behind a CLI option.
types_to_files_to_symbols = {} | ||
# Group symbols by file and type. | ||
doc_index.each do |index_item| | ||
if index_item.parent_in_code.nil? && (index_item.type.name == "Constant" || index_item.type.name == "Function") |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You can just use docs
instead of doc_index
if you just want top-level items, then won't need the parent_in_code
check and will be more efficient.
[group.compact, docs] | ||
|
||
globals_grouped_by_file = self.group_globals_by_file(docs, doc_index) | ||
[group.compact, docs + globals_grouped_by_file] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You need to go back to group_docs()
and figure out the code there -- the advice to start in this routine was based (again :-)) on your other design.
Ruby hash iteration order is guaranteed - I think that is all you need to prove that you don't need any further sorting.
types_to_files_to_symbols.each do |type_name, files| | ||
types_to_file_groups[type_name] ||= [] | ||
files.each do |file, declarations| | ||
file_group = make_group(declarations, file, '') |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this group is the one that should have the abstract "The following thingies are available globally" (you could write "are provided by " given that you're adding source filenames into the UI.
And the group below (line 103) is the one that should have the abstract "The following files provide thingies" or something?
doc_index
iterable.custom_categories
are processed, group any remaining global constants / functions further based on the file they're in.Staged sample: https://serve-dot-zipline.appspot.com/asset/55d078ae-b243-597e-9a9d-257f931f2723/zpc/63fc25cv8le/GMSGeometryUtils%2BFunctions.html
Resolves #1400