RFC proc-macro structure

[taqtiqa-mark]

Related to issue #81
In the course of issue #112

I had a look at the proc-macro crate, with a view to fixing #112. Not being a proc-macro guru I'm a little intimidated/lost by the current structure.
The proposal is to, in the first instance restructure the code into the following pipeline:

The file layout would be:

src
|-- lib.rs
`-- trace
    |-- analyze.rs
    |-- codegen.rs
    |-- lower.rs
    `-- parse.rs

New proc-macro-attributes, proc-macro-functions would be expected to follow the same convention.

The idea would be to write tests as the code is migrated.

A WIP example is in the issue-1 branch of tracing-attributes-http:

https://github.com/taqtiqa-mark/tracing-attributes-http/tree/issue-1/src

Thoughts?

[andylokandy]

Thank you for bringing this up, the proposal looks petty neat to me. The current codebase is not intended to be this messy and mysterious... It's simply because I've put all ideas into it in one night and to prove they work, so the code structure was not seriously taken into consideration.

To leave some useful information for who is interested in refactoring the macro (I may do it months later if no one does it by that time), here is the original place where some of the codes are copied from:

• https://github.com/dtolnay/async-trait: for adding lifetime to arguments, when elaborating an async fn into fn -> impl Future.
• https://github.com/tokio-rs/tracing/blob/master/tracing-attributes/src/expand.rs: for detecting the async fn that is already transformed to fn -> impl Future by async-trait. We've to distinguish it from fn -> impl Future that is written by the user because for the latter, we instrument it like normal fn instead of async fn.

[andylokandy]

The reason why we've to elaborate async fn into fn -> impl Future is that, for an async fn foo(), we have to instrument the Span::enter_with_local_parent in the first call to foo(), but not in the poll() or .await, because it's the only chance that local parent is prenent in the context.

[taqtiqa-mark]

I think to begin with it'll be baby steps:

1. Restructure the code layout and introduce tests.
2. Error reporting / UI
3. Once some tests are in place would be to introduce a model, etc.

[breezewish]

RFC is a generally great idea for such purpose. However with my current practice experience it may affect agility or hard to be followed until we find a good balance / standard about what should be tracked by a RFC.

I'm also thinking about a lighter way for summarize new changes which should be easier to be followed: always describe the change with more details in the issue + finalize ideas in the doc comment + verbose function comments. We should also have verbose comments for existing code bases.

What do you think?

[andylokandy]

From my personal experience in open source projects, for this kind of small project, I'll directly open a pull request to bootstrap the discussion. Although there are risks of going into a completely wrong direction and wasting time, I found it rather efficient to drive me and the reviewers to a better solution even if my first try is bad.

[taqtiqa-mark]

Agreed. The main risk here is rejecting the whole pipeline idea. I don't propose the RFC be more detailed than what it is now, e.g. the Model is undefined/unspecified - it'll emerge, as you say small PR by small PR.

The goal is to keep the proc-macro working the whole time. I'll try do this by changing the code once it is covered by a test case, so related to #81.

So I believe we are agreed, this will not land with a big-bang single PR.
Rather smaller PRs will indicate how they are heading in the direction set out in this RFC.
Correct?

[taqtiqa-mark]

Voided by PR #127 rejection.