This is an archive of the discontinued LLVM Phabricator instance.

[clang-doc] Improving Markdown Output
ClosedPublic

Authored by Clayton on Jan 17 2020, 1:09 PM.

Details

Summary
This change has two components. The moves the generated file
 for a namespace to the directory named after the namespace in
 a file named 'index.<format>'. This greatly improves the browsing
 experience since the index page is shown by default for a directory.
 
 The second improves the markdown output by adding the links to the
 referenced pages for children objects and the link back to the source
 code.

Diff Detail

Event Timeline

Clayton created this revision.Jan 17 2020, 1:09 PM
Herald added a project: Restricted Project. · View Herald TranscriptJan 17 2020, 1:09 PM
Clayton added a project: Restricted Project.Jan 17 2020, 1:10 PM
juliehockett added a comment.EditedJan 21 2020, 8:21 AM

Thanks so much for doing this! Would you be able to link some screenshots? Just so I can have a better sense of what's changing here.

clang-tools-extra/clang-doc/Representation.h
271

s/Reference/Info

The output for for html did not change - what changed was the path for namespaces. For example the "async" namespace was in documented in async.html, and the types and functions in async where in async/*.html. After this change the "async" namespace is documented in async/index.html. This makes browsing very nice.

On the markdown side, I added the link functionality that existed on the HTML output for linking to classes and child namespaces.

BeforeAfter
Clayton updated this revision to Diff 239441.Jan 21 2020, 3:04 PM

Updated comment in Representation.h based on reviewer feedback.

Clayton marked 2 inline comments as done.Jan 21 2020, 3:05 PM
Clayton added inline comments.
clang-tools-extra/clang-doc/Representation.h
271

Done.

phosek added inline comments.Jan 21 2020, 8:08 PM
clang-tools-extra/clang-doc/MDGenerator.cpp
280

level should be Level.

281

Nit: no extra empty line.

295

No need for OK, you can simply do if (FileErr).

299

No curly braces for blocks with a single statement according to LLVM style.

304

The same here, no curly braces for blocks with a single statement according to LLVM style.

309

Here as well.

320

The same here, both the error checking and curly braces.

clang-tools-extra/clang-doc/Representation.cpp
124

iter should be Iter (or just I) according to LLVM style.

134

No curly braces for blocks with a single statement.

146

No curly braces for blocks with a single statement.

159

No curly braces for blocks with a single statement.

Clayton updated this revision to Diff 239579.Jan 22 2020, 6:49 AM
Clayton marked 13 inline comments as done.

Updates to conform to LLVM style guide per reviewer feedback.

clang-tools-extra/clang-doc/MDGenerator.cpp
280
phosek accepted this revision.Jan 30 2020, 12:07 PM

LGTM % one minor nit, do you want me to land this for you?

clang-tools-extra/clang-doc/assets/index.js
34–38

You could omit braces here as well (we've been following C/C++ style guide for JS).

This revision is now accepted and ready to land.Jan 30 2020, 12:07 PM
Clayton updated this revision to Diff 241570.Jan 30 2020, 1:31 PM

Removed unnecessary braces in index.js

Yes, please merge the change. Out of curiosity, is there a linter that can be used to help check for style rule adherence?

This revision was automatically updated to reflect the committed changes.
Herald added a project: Restricted Project. · View Herald TranscriptJan 31 2020, 2:26 PM
Herald added a subscriber: cfe-commits. · View Herald Transcript
Clayton reopened this revision.Feb 3 2020, 7:20 AM

Fixing build error

This revision is now accepted and ready to land.Feb 3 2020, 7:20 AM
Clayton updated this revision to Diff 242066.Feb 3 2020, 7:21 AM

build error fixed.

This revision was automatically updated to reflect the committed changes.
Clayton reopened this revision.Feb 6 2020, 3:09 PM

Fixing unit tests affected by this change.

This revision is now accepted and ready to land.Feb 6 2020, 3:09 PM
Clayton updated this revision to Diff 243027.Feb 6 2020, 3:09 PM

Updating tests affected by this change.

This revision was automatically updated to reflect the committed changes.
phosek added a comment.Feb 7 2020, 7:43 PM

This is failing on Windows:

../../clang-tools-extra/unittests/clang-doc/MDGeneratorTest.cpp(77): error:       Expected: Expected
      Which is: "# namespace Namespace\n\n\n\n## Namespaces\n\n* [ChildNamespace](../ChildNamespace/index.md)\n\n\n## Records\n\n* [ChildStruct](../ChildStruct.md)\n\n\n## Functions\n\n### OneFunction\n\n* OneFunction()*\n\n\n\n## Enums\n\n| enum OneEnum |\n\n--\n\n\n\n\n\n"
To be equal to: Actual.str()
      Which is: "# namespace Namespace\n\n\n\n## Namespaces\n\n* [ChildNamespace](..\\ChildNamespace\\index.md)\n\n\n## Records\n\n* [ChildStruct](..\\ChildStruct.md)\n\n\n## Functions\n\n### OneFunction\n\n* OneFunction()*\n\n\n\n## Enums\n\n| enum OneEnum |\n\n--\n\n\n\n\n\n"
With diff:
@@ -5,5 +5,5 @@
 ## Namespaces
 
-* [ChildNamespace](../ChildNamespace/index.md)
+* [ChildNamespace](..\\ChildNamespace\\index.md)
 
 
@@ -10,5 +10,5 @@
 ## Records
 
-* [ChildStruct](../ChildStruct.md)
+* [ChildStruct](..\\ChildStruct.md)
 
 

[  FAILED  ] MDGeneratorTest.emitNamespaceMD (1 ms)
[----------] 1 test from MDGeneratorTest (1 ms total)

[----------] Global test environment tear-down
[==========] 1 test from 1 test case ran. (1 ms total)
[  PASSED  ] 0 tests.
[  FAILED  ] 1 test, listed below:
[  FAILED  ] MDGeneratorTest.emitNamespaceMD

 1 FAILED TEST
Clayton reopened this revision.Feb 12 2020, 9:15 AM

Re-opening to fix windows tests failures.

This revision is now accepted and ready to land.Feb 12 2020, 9:15 AM
Clayton updated this revision to Diff 244204.Feb 12 2020, 9:20 AM

Making paths in markdown files be posix style. This fixes the tests on windows hosts.

phosek closed this revision.Mar 4 2020, 2:41 PM
phosek reopened this revision.
This revision is now accepted and ready to land.Mar 4 2020, 2:41 PM
This revision was automatically updated to reflect the committed changes.
phosek added a comment.Mar 4 2020, 3:27 PM

This is still failing on Windows:

******************** TEST 'Extra Tools Unit Tests :: clang-doc/./ClangDocTests.exe/MDGeneratorTest.emitNamespaceMD' FAILED ********************
Note: Google Test filter = MDGeneratorTest.emitNamespaceMD

[==========] Running 1 test from 1 test case.

[----------] Global test environment set-up.

[----------] 1 test from MDGeneratorTest

[ RUN      ] MDGeneratorTest.emitNamespaceMD

C:\ps4-buildslave2\llvm-clang-lld-x86_64-scei-ps4-windows10pro-fast\llvm-project\clang-tools-extra\unittests\clang-doc\MDGeneratorTest.cpp(77): error:       Expected: Expected

      Which is: "# namespace Namespace\n\n\n\n## Namespaces\n\n* [ChildNamespace](../ChildNamespace/index.md)\n\n\n## Records\n\n* [ChildStruct](../ChildStruct.md)\n\n\n## Functions\n\n### OneFunction\n\n* OneFunction()*\n\n\n\n## Enums\n\n| enum OneEnum |\n\n--\n\n\n\n\n\n"

To be equal to: Actual.str()

      Which is: "# namespace Namespace\n\n\n\n## Namespaces\n\n* [ChildNamespace](../ChildNamespace/index.md)\n\n\n## Records\n\n* [ChildStruct](..//ChildStruct.md)\n\n\n## Functions\n\n### OneFunction\n\n* OneFunction()*\n\n\n\n## Enums\n\n| enum OneEnum |\n\n--\n\n\n\n\n\n"

With diff:

@@ -10,5 +10,5 @@

 ## Records

 

-* [ChildStruct](../ChildStruct.md)

+* [ChildStruct](..//ChildStruct.md)

 

 



[  FAILED  ] MDGeneratorTest.emitNamespaceMD (1 ms)

[----------] 1 test from MDGeneratorTest (1 ms total)



[----------] Global test environment tear-down

[==========] 1 test from 1 test case ran. (1 ms total)

[  PASSED  ] 0 tests.

[  FAILED  ] 1 test, listed below:

[  FAILED  ] MDGeneratorTest.emitNamespaceMD



 1 FAILED TEST
phosek reopened this revision.Mar 6 2020, 2:01 PM
This revision is now accepted and ready to land.Mar 6 2020, 2:01 PM
This revision was automatically updated to reflect the committed changes.