This is an archive of the discontinued LLVM Phabricator instance.

[clang-doc] Add link to source code in file definitions
ClosedPublic

Authored by DiegoAstiazaran on Jul 30 2019, 3:37 PM.

Details

Summary

Two command line options have been added to clang-doc.

--repository=<string>       - URL of repository that hosts code; used for links to definition locations.
--source-root=<string>      - Directory where processed files are stored. Links to definition locations will only be generated if the file is in this dir.

If the file is in the root-directory and a repository options is passed; a link to the source code will be rendered by the HTML generator.

Diff Detail

Event Timeline

Eugene.Zelenko retitled this revision from [clang-format] Add link to source code in file definitions to [clang-doc] Add link to source code in file definitions.Jul 30 2019, 5:20 PM

It'll be reasonable to mention new command-line arguments in documentation and Release Notes.

jakehehrlich added inline comments.Aug 2 2019, 3:49 PM
clang-tools-extra/clang-doc/HTMLGenerator.cpp
412

Add a comment here that this is the github/googlesource notation for this that way in the future people arren't confused when it doesn't work for other hosting pages

413–414

Can you put these in the link so that the link is larger than a single number? e.g. "303 of file foo.c" should be linkified rather than just "303" which is how I read the code now.

clang-tools-extra/clang-doc/Mapper.cpp
104–105

Do you actually need to do this? Feels like a bug in replace_path_prefix per its own documentation if you do.

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
211
  1. Do we need to add this for the user?
  2. Can we use https by default if we need this?
DiegoAstiazaran marked 7 inline comments as done.

Change http to https as the default fix to the repository link.
Add new flags to clang-doc documentation.

DiegoAstiazaran added inline comments.
clang-tools-extra/clang-doc/HTMLGenerator.cpp
413–414

"303" is linkified to the specific line in the source code but also "foo.c" is linkified to the top of the source code page.
This is how it is done in Doxygen documentation.
I think it would look weird to have " of file " linkified. But talking to @phosek, we agreed that it would be better to remove the whole "Defined at ..." and make the info name linkified to the definition, with a tooltip that shows "foo.c:303".
So I think we could leave it like this for now and later, in another patch (this will require some CSS), do what I just mentioned. What do you think?

clang-tools-extra/clang-doc/Mapper.cpp
104–105

replace_path_prefix simply calls substr() on the path so if the prefix does not include the separator at the end, the resulting path will have it at the beginning.

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
211

Not required but I consider it'd be nice to have it.
You're right, https should be the default.

juliehockett added inline comments.Aug 5 2019, 4:55 PM
clang-tools-extra/clang-doc/HTMLGenerator.cpp
413–414

While the tooltip idea seems interesting, I'm inclined to keep the "Defined at" portion and an actual link with the text for now. I'd want to see an example of what the tooltip option would look like before going with it.

For now, the separate line number and file linkification SGTM.

clang-tools-extra/clang-doc/Mapper.cpp
40

Don't use auto here, since it's not immediately obvious what the type is.

104–105

Leave a comment to that effect, then.

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
79

Can we call this --source-root?

211

This is fine, but please add a test case for the when the user omits the prefix.

clang-tools-extra/docs/clang-doc.rst
93

Formatting here is a bit weird

DiegoAstiazaran marked 7 inline comments as done.
DiegoAstiazaran edited the summary of this revision. (Show Details)

Add comments.
Change name of flag; root-directory -> --source-root
Moved fixing of repository link to ClangDocContext constructor and add test where the prefix is omitted.
RepositoryLink in ClangDocContext struct and writeFileDefinition function is now llvm::Optional<>

clang-tools-extra/docs/clang-doc.rst
93

Do you mean the almost empty line that's only "-"? This is because the description of the flag starts with \n.

R"(
URL of repository that hosts code.
Used for links to definition locations.)"

I used the same format used by clang-tidy, it has this format for all the multi-line flag descriptions.

Remove unnecessary type casting.

juliehockett added inline comments.Aug 7 2019, 1:31 PM
clang-tools-extra/clang-doc/Representation.h
386

Move to .cpp file (now that it has a non-trivial implementation)

388

Comment

DiegoAstiazaran marked 2 inline comments as done.

Add comments.
Move definition of ClangDocContext constructor to .cpp file.

Rebase to master

This revision is now accepted and ready to land.Aug 9 2019, 9:09 AM
This revision was automatically updated to reflect the committed changes.
Herald added a project: Restricted Project. · View Herald TranscriptAug 9 2019, 10:49 AM