Lread cljs proper cljs meta file fix #2
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
For maintainability and to reduce confusion, I removed unused: html writer, resources and project.clj. This will also avoid unused sources coming into play for upcoming unit test work.
Updated ClojureScript's reader to use the :file metadata returned by analysis. It formerly set :file to the actual path of the :file it was analysing. This change matches the Clojure reader behaviour and allows for potemkin import-vars type manipulation of metadata to, for example, point at an alternate var's docs in a different source file. To verify readers are still returning data that we expect, I added some tests based on the existing playgound under test-sources. The tests are a good start but not comprehensive and should be extended as needed. Circleci config is included to automatically run tests on commit. While adding tests, I noticed small bugs and made corrections: 1. The ClojureScript reader now sorts protocol methods by name. This matches the behaviour of the Clojure reader. 2. The Clojure reader will now add a single var for each defrecord with the name of the defrecord. This matches the ClojureScript behaviour and is apparently the desired behaviour for cljdoc. For consistency and testability: - we are now removing keys with empty/nil values from reader analysis maps. - to be conistent with the ClojureScript reader, the Clojure reader no longer returns :file :line :column :end-column and :end-line on the namespace element. Notes: As part of this change, the ClojureScript reader will stop supressing protocol functions when the actual source does not match the :file metadata. This allows for a tool such as import-vars to point to, and have documented, an imported protocol function. No action was needed for the Clojure reader to make this work. This change was made a bit challenging due to cljdoc's usage of codox's root-dir and :file metadata: - The original intent of codox is that the config :root-dir point to the project (aka git) root of a project and that the :file metadata was simply what was returned by analysis. Codox added the :path to analysis metadata to resolve :file to the :root-dir. - Cljdoc does not set the :root-dir to the project root, ignores the :path and assumes that the :file is always relative to configured :source-path. Although this usage works for cljdoc, it did sprain my brain while making this change. - To compensate, I have been careful to ensure that :file continues to always be relative to the the configured :source-path. Another oddity was that altered :file metadata is being resolved to paths within the jar file when codox is called from cljdoc. This might be due to the way the classpath is setup when doing an analysis run. My change is coded to handle this situation when it arises.
|
thanks @martinklepsch! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Includes #1 and some more work towards extracting the core bits of Codox into a reusable library that is focused on extracting plain data from Clojure and ClojureScript runtimes.
Mostly opening this to share some initial work I've done with @lread