Page MenuHomePhabricator

[clang-doc] Add html links to references

Authored by DiegoAstiazaran on Jun 21 2019, 12:21 PM.



<a> tags are added for the parents and members of records and return type and params of functions.
The link redirects to the reference's info file.
The directory path where each info file will be saved is now generated in the serialization phase and stored as an attribute in each Info.
Bitcode writer and reader were modified to handle the new attributes.

Diff Detail

Event Timeline

General design thought: could we move the path name construction to Serialize.cpp? Essentially, move the logic that builds the path name from the namespaces and name to the serialize step (you'll have to add the OutDirectory to the ClangDocContext so that you can access it in the mapper), and then the GetInfoOuputFile() function in ClangDocMain.cpp would take the Info.Path string as a parameter and do the directory construction and whatnot.

With that, you could then also add the Path field to References, so that you wouldn't need to pass a map around in the generation phase. What do you think?

Eugene.Zelenko added inline comments.

Anonymous namespace is used for functions when LLVM Coding Guidelines tells using static for same purpose.


You don't need to assign empty string. See readability-redundant-string-init.

DiegoAstiazaran edited the summary of this revision. (Show Details)

Path name generation was moved to serialization phase as @juliehockett suggested.
Empty string declaration fixed.
Removed anonymous namespaces.

DiegoAstiazaran marked 2 inline comments as done.Jun 24 2019, 4:01 PM
ormris removed a subscriber: ormris.Jun 24 2019, 4:04 PM
juliehockett added inline comments.Jun 24 2019, 5:00 PM

Actually, since these aren't used outside of this file, please use the static keyword instead of wrapping them in a namespace.


Use llvm::sys::path to allow for other platforms that use a different separator.


Same here, just use static.




Also for members


Also for param references, if applicable


Can we do the path construction for virtual bases as well, so they can be linked too?


Add path information to these references as well


formatting change?

DiegoAstiazaran marked 10 inline comments as done.
DiegoAstiazaran retitled this revision from [clang-doc] Add html links to the parents of a RecordInfo to [clang-doc] Add html links to references.
DiegoAstiazaran edited the summary of this revision. (Show Details)

Links added for a function's return type and parameters' types and for a record's members' type.
Fixed path generation to support multiple platforms.


Yes, clang-format did that change.

DiegoAstiazaran edited the summary of this revision. (Show Details)

The links are now generated using the nodes structure introduced by D63857.

Rebase after D52847 was pushed.
Path added to parent Info in serialization, this is required after D63911 was pushed.

The code looks good to me. I'll let Julie give the final architectural approval.

juliehockett added inline comments.Jul 9 2019, 9:24 AM

You shouldn't need the prefixed ::


While you're here, can you update this error to something like "Invalid reference type for parent namespace"?


nit: use ++Enum.Namespace.begin()


Could it add the OutDirectory here, and just store the relative path in I->Path? Since OutDirectory is constant throughout. You also wouldn't have to plumb it through all the serialize functions.

DiegoAstiazaran marked 5 inline comments as done.

The info path generated in serialization was the composite of the out directory and the parent namespaces. Now it's only the parent namespaces; the out directory path is appended until the directory is actually created in the doc generation phase.

DiegoAstiazaran added inline comments.Jul 9 2019, 1:15 PM

++ operator cannot be used in that expression because it's not assignable.

I've also just noticed that the YAML generator is missing from this -- could you add the Path fields to hat output as well?


Now that the paths aren't absolute, you'll need to make this relative to the current path (something like

Use relative paths for references/links within files.
Don't fill namespaces of parentInfo in serialization and path is only generated when the parent is the global namespace.
Add new fields (Path in Reference and Path in Info) to YAML output and tests.

juliehockett added inline comments.Jul 10 2019, 3:58 PM

This text should be rendered inline


This text should be rendered inline, if possible.

DiegoAstiazaran marked an inline comment as done.Jul 10 2019, 4:01 PM

In tag nodes with children that are not inline, two text nodes that are adjacent won't have a new line between them. Tag nodes are still rendered in their own line.


is now rendered as

  A B
DiegoAstiazaran marked 2 inline comments as done.Jul 10 2019, 4:54 PM
juliehockett accepted this revision.Jul 11 2019, 8:38 AM
This revision is now accepted and ready to land.Jul 11 2019, 8:38 AM
DiegoAstiazaran edited the summary of this revision. (Show Details)
This revision was automatically updated to reflect the committed changes.
Herald added a project: Restricted Project. · View Herald TranscriptJul 12 2019, 11:31 AM