Skip to content

#467: generate summary XML in docs command#951

Open
nacNAC333 wants to merge 2 commits into
objectionary:masterfrom
nacNAC333:467
Open

#467: generate summary XML in docs command#951
nacNAC333 wants to merge 2 commits into
objectionary:masterfrom
nacNAC333:467

Conversation

@nacNAC333

Copy link
Copy Markdown

Fixes #467

Adds summary XML file generation to the docs command. After generating HTML documentation, the command now also produces a summary.xml file in <eodoc> format listing all packages and objects.

Changes:

  • Add xmlEscape() helper for safe XML entity escaping
  • Generate summary.xml with <eodoc> root, <package> and <object> children
  • Include packages and objects count attributes on root element

@yegor256

Copy link
Copy Markdown
Member

@nacNAC333 Thanks for your contribution! Unfortunately, we can't merge it without tests. Every feature we add and every bug we fix must be accompanied by at least one new test that confirms that the code was not working before. Without such a test, how can we know that what you commit actually works?

@Favixx Favixx left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

docs command crashes — rel is not defined

Running the docs test suite on this branch (test/commands/test_docs.js) fails: line 178 calls rel(summary), but rel is not defined or imported anywhere in src/commands/docs.js.

Error generating documentation: ReferenceError: rel is not defined
    at src/commands/docs.js:178:15
    at elapsed (src/elapsed.js:23:10)
    at module.exports [as docs] (src/commands/docs.js:124:10)

The exception is caught at line 149, so execution aborts before summary.xml is written — the feature never produces output, and the generates HTML files for files and packages test fails.

Suggested follow-ups:

  1. Replace rel(summary) with something defined, e.g. path.relative(output, summary).
  2. The nested O(packages × xmirs) loop re-derives data that packages_info already groups — consider reusing it instead of recomputing path.relative per xmir per package.
  3. Please add a test asserting summary.xml is created with the expected packages/objects counts — none exists currently, which is why this regression slipped through.

@nacNAC333 nacNAC333 force-pushed the 467 branch 2 times, most recently from 553861a to b371f0f Compare June 2, 2026 19:30
@nacNAC333

Copy link
Copy Markdown
Author

@yegor256 Test added in the second commit — generates summary XML with correct package and object counts verifies the file is created and checks package/object counts, package names, and object names. Also rebased on latest master.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs.js doesn't generate a summary XML file

3 participants