search

OvermindDL1 / ex_spirit

27 stars 1 forks source link

Dummy functions and macros for ExDocs #5

Closed tmbb closed 7 years ago

tmbb commented 7 years ago

Added some dummy functions and macros to get prettier and more useful ExDocs. An error will be raised at compile-time (runtime) if any of the dummy macros (functions) is ever called.

tmbb commented 7 years ago

The "narrative" part of the docs still needs some work (explaining what exactly is the context_ast parameter, for example).

OvermindDL1 commented 7 years ago

Hah, that's cool, just what needed to be done. ^.^

It is pretty sizeable, is it ready to merge or are you still working on it? I'll look at it closer soon. :-)

tmbb commented 7 years ago

It's ready to merge if you're happy with it.

I didn't do much work, actually. I mostly took the text you've written and added it to the docstrings of the dummy functions. I also corrected the phrasing of the text in some places where I felt it was a little awkward.

You can add something to the narrative part of the docs to explain the ast_context thing, and there should be a guide on how to write your own terminal parsers or parsers that take parameters, but the information that's in the PR is pretty much the same as the one that was there before.

tmbb commented 7 years ago

Unfortunately, I can't render the docs with ex_doc_makeup (still not on hex.pm) because makeup depends on ExSpirit.

OvermindDL1 commented 7 years ago

Lol, you'd think it would detect that it is itself... I wonder if there is a dep override option for just using the 'current project' as the override... I cannot recall such an option, we need it if so to break cyclic dependencies...

OvermindDL1 commented 7 years ago

Hmm, maybe we could just do a dep dependency override on a path: ".", I wonder if that would break mix...

tmbb commented 7 years ago

I wonder if that would break mix...

Just checked, it does break mix :p There must be ways of hacking our way around this, but they're probably no worth it.

tmbb commented 7 years ago

I cannot recall such an option, we need it if so to break cyclic dependencies...

Given that ExSpirit is one of only the 2 or 3 packages that can't be documented with ex_doc_makeup it's really not worth it to even think about adding such an option xD

OvermindDL1 commented 7 years ago

Just checked, it does break mix :p There must be ways of hacking our way around this, but they're probably no worth it.

Sounds like a bug report to report. ^.^

Or a feature request?

Given that ExSpirit is one of only the 2 or 3 packages that can't be documented with ex_doc_makeup it's really not worth it to even think about adding such an option xD

Aww, but it would be awesome. ^.^

tmbb commented 7 years ago

Aww, but it would be awesome. ^.^

Lol, we can find out how the core team manages to get docs working for the standard library, despite elixir being required to compile ex_doc. There might be some trickery involved which we can copy.

OvermindDL1 commented 7 years ago

Lol, we can find out how the core team manages to get docs working for the standard library, despite elixir being required to compile ex_doc. There might be some trickery involved which we can copy.

Ah, good idea, ping me if you find out? :-)

/me is too busy at th emoment but can look later if you ping later?