Skip to content

Commit

Permalink
revert(polyglot): Remove polyglot mode
Browse files Browse the repository at this point in the history 
BREAKING CHANGE: I'd like to still support C++ and other languages in the future! But I'm much
happier doing so by separating the extraction & input phases to the degree that documentation.js can
read the output of another module that extracts JSDoc comments from C++ code, rather than having CPP
support in it.

Fixes #850. Fixes #731. Fixes #702. Fixes #132.
  • Loading branch information
@tmcw
tmcw committed Jul 27, 2017
1 parent b42c0d7 commit 5b373ff
Show file tree
Hide file tree
Showing 15 changed files with 37 additions and 1,101 deletions.
205 changes: 2 additions & 203 deletions __tests__/__snapshots__/bin.js.snap
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ exports[`--config 1`] = `
<html>
<head>
<meta charset='utf-8' />
<title>documentation 4.0.0-rc.1 | Documentation</title>
<title>documentation 4.0.0 | Documentation</title>
<meta name='viewport' content='width=device-width,initial-scale=1'>
<link href='assets/bass.css' type='text/css' rel='stylesheet' />
<link href='assets/style.css' type='text/css' rel='stylesheet' />
Expand All @@ -17,7 +17,7 @@ exports[`--config 1`] = `
<div class='fixed xs-hide fix-3 overflow-auto max-height-100'>
<div class='py1 px2'>
<h3 class='mb0 no-anchor'>documentation</h3>
<div class='mb1'><code>4.0.0-rc.1</code></div>
<div class='mb1'><code>4.0.0</code></div>
<input
placeholder='Filter'
id='filter-input'
Expand Down Expand Up @@ -1819,204 +1819,3 @@ f5 comment
`;
exports[`lint command generates lint output 1`] = `""`;
exports[`polyglot mode 1`] = `
Array [
Object {
"augments": Array [],
"context": Object {
"file": "[path]",
"loc": Object {
"end": Object {
"column": 3,
"line": 40,
},
"start": Object {
"column": 1,
"line": 35,
},
},
},
"description": Object {
"children": Array [
Object {
"children": Array [
Object {
"position": Object {
"end": Object {
"column": 35,
"line": 1,
"offset": 34,
},
"indent": Array [],
"start": Object {
"column": 1,
"line": 1,
"offset": 0,
},
},
"type": "text",
"value": "This method moves a hex to a color",
},
],
"position": Object {
"end": Object {
"column": 35,
"line": 1,
"offset": 34,
},
"indent": Array [],
"start": Object {
"column": 1,
"line": 1,
"offset": 0,
},
},
"type": "paragraph",
},
],
"position": Object {
"end": Object {
"column": 35,
"line": 1,
"offset": 34,
},
"start": Object {
"column": 1,
"line": 1,
"offset": 0,
},
},
"type": "root",
},
"examples": Array [],
"loc": Object {
"end": Object {
"column": 3,
"line": 40,
},
"start": Object {
"column": 1,
"line": 35,
},
},
"members": Object {
"events": Array [],
"global": Array [],
"inner": Array [],
"instance": Array [],
"static": Array [],
},
"name": "hexToUInt32Color",
"namespace": "hexToUInt32Color",
"params": Array [
Object {
"lineNumber": 3,
"name": "hex",
"title": "param",
"type": Object {
"name": "string",
"type": "NameExpression",
},
},
],
"path": Array [
Object {
"name": "hexToUInt32Color",
},
],
"properties": Array [],
"returns": Array [
Object {
"description": Object {
"children": Array [
Object {
"children": Array [
Object {
"position": Object {
"end": Object {
"column": 6,
"line": 1,
"offset": 5,
},
"indent": Array [],
"start": Object {
"column": 1,
"line": 1,
"offset": 0,
},
},
"type": "text",
"value": "color",
},
],
"position": Object {
"end": Object {
"column": 6,
"line": 1,
"offset": 5,
},
"indent": Array [],
"start": Object {
"column": 1,
"line": 1,
"offset": 0,
},
},
"type": "paragraph",
},
],
"position": Object {
"end": Object {
"column": 6,
"line": 1,
"offset": 5,
},
"start": Object {
"column": 1,
"line": 1,
"offset": 0,
},
},
"type": "root",
},
"title": "returns",
"type": Object {
"name": "number",
"type": "NameExpression",
},
},
],
"sees": Array [],
"tags": Array [
Object {
"description": null,
"lineNumber": 2,
"name": "hexToUInt32Color",
"title": "name",
},
Object {
"description": null,
"lineNumber": 3,
"name": "hex",
"title": "param",
"type": Object {
"name": "string",
"type": "NameExpression",
},
},
Object {
"description": "color",
"lineNumber": 4,
"title": "returns",
"type": Object {
"name": "number",
"type": "NameExpression",
},
},
],
"throws": Array [],
"todos": Array [],
},
]
`;
8 changes: 4 additions & 4 deletions __tests__/__snapshots__/test.js.snap
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,11 +42,11 @@ Array [
"loc": SourceLocation {
"end": Position {
"column": 1,
"line": 12,
"line": 10,
},
"start": Position {
"column": 0,
"line": 10,
"line": 8,
},
},
},
Expand Down Expand Up @@ -142,11 +142,11 @@ Array [
"loc": SourceLocation {
"end": Position {
"column": 3,
"line": 9,
"line": 7,
},
"start": Position {
"column": 0,
"line": 7,
"line": 5,
},
},
"members": Object {
Expand Down
18 changes: 0 additions & 18 deletions __tests__/bin.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,13 +58,6 @@ test('defaults to parsing package.json main', async function() {
expect(data.length).toBeTruthy();
});

test('polyglot mode', async function() {
const data = await documentation([
'build fixture/polyglot/blend.cpp --polyglot'
]);
expect(normalize(data)).toMatchSnapshot();
});

test('accepts config file', async function() {
const data = await documentation([
'build fixture/sorting/input.js -c fixture/config.json'
Expand Down Expand Up @@ -126,17 +119,6 @@ test('extension option', async function() {
expect(data.length).toBe(1);
});

/*
* This tests that parseExtension adds extensions to smartGlob's
* look through directories.
*/
test('polyglot + parseExtension + smartGlob', async function() {
const data = await documentation([
'build fixture/polyglot ' + '--polyglot --parseExtension=cpp'
]);
expect(data.length).toBe(1);
});

test('extension option', function() {
return documentation(['build fixture/extension.jsx']);
});
Expand Down
2 changes: 0 additions & 2 deletions __tests__/fixture/external.input.js
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
require('external');
require('external2');
require('module-not-found');
// non-js require
require('./polyglot/blend.cpp');

/**
* I am in `external.input.js`.
Expand Down
Loading

3 comments on commit 5b373ff

@mmomtchev
Copy link
Contributor

Choose a reason for hiding this comment

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

@tmcw I forked documentationjs and I restored polyglot (the merge was surprisingly easy 4 years later)
I intend to use this fork to document my project gdal-async which is a Node.js addon where a majority of the JS classes are backed by C++ implementations
I cannot stress enough the importance of this project since yuidoc, the only other documentation solution that supports both jsdoc and C++ is not maintained since 2016
Doxygen and sphinx are not native JS documentation generators and lack many features - Node.js addons are a very special kind of projects - they are JS projects written in C++

I have lots of spare time on my hands and I need this project, so:

  • If you are willing, I can maintain the polyglot mode in documentationjs
  • If you prefer, I can transform polyglot into a separate package to be interfaced with documentationjs through some well-defined API
  • Or otherwise, I will commit to maintaining this fork

@tmcw
Copy link
Member Author

@tmcw tmcw commented on 5b373ff Nov 9, 2021

Choose a reason for hiding this comment

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

Hi @mmomtchev! Thanks for your work on gdal-async, it's very cool :) @anthony-redFox is really the one maintaining documentation.js nowadays, he'd be the best person to ask about whether reintroducing this to the project would be feasible!

@mmomtchev
Copy link
Contributor

Choose a reason for hiding this comment

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

@tmcw, ok thanks a lot for your response, and of course glad to hear that gdal-async is useful
gdal-async is a complex project and once I am able to produce a quality documentation with document, I will consider my work complete and then we will discuss what could be done with this new parser

Please sign in to comment.