Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

please provide location info for warnings #5901

Closed
vicuna opened this issue Jan 22, 2013 · 7 comments
Closed

please provide location info for warnings #5901

vicuna opened this issue Jan 22, 2013 · 7 comments

Comments

@vicuna
Copy link

vicuna commented Jan 22, 2013

Original bug ID: 5901
Reporter: Hendrik Tews
Assigned to: @zoggy
Status: assigned (set by Hendrik Tews on 2013-01-22T21:41:55Z)
Resolution: open
Priority: normal
Severity: feature
Version: 4.00.1
Category: ocamldoc
Tags: junior_job
Duplicate of: #8401
Related to: #7084 #7187
Monitored by: junsli @hcarty

Bug description

Hi,

ocamldoc outputs several types of warnings without an information about the point in the source that triggered the warning. For instance

Warning: Element some_xref not found

It's quite time consuming to find the point in the source that triggered this warning.

Bye,

Hendrik

@vicuna
Copy link
Author

vicuna commented Jul 28, 2013

Comment author: @gasche

I'm marking this as a "junior job" because this is non-critic code that can be improved easily. But this would still require pervasives changes to the ocamldoc codebase (to have location information flowing to the places that throw warnings), so it should not be considered easy either.

@vicuna
Copy link
Author

vicuna commented Nov 24, 2015

Comment author: junsli

Hello, what's the plan on this bug? I'd like to fix it.

@vicuna
Copy link
Author

vicuna commented Nov 24, 2015

Comment author: @gasche

junsli: please feel free to go ahead. Where you asking about particular directions of where to go in the source? (I don't know, but I would just grep fragments of the text of the warning above, to find where those warnings are emitted.)

@vicuna
Copy link
Author

vicuna commented Nov 24, 2015

Comment author: junsli

Hi gasche, Thanks. I meant the target plan, but I guess it does not matter. I'll work on this anyway.

@vicuna
Copy link
Author

vicuna commented Dec 22, 2015

Comment author: junsli

Some updates: A good starting point of propagating location information from parser upwards is odoc_parser.main, instead of returning string of description and remaining text, location info should also be returned.

It is still unclear why odoc_lexer (and odoc_text_lexer) maintains line_number (and char_number) instead of using the line information in lexbuf.

@vicuna
Copy link
Author

vicuna commented Dec 29, 2015

Comment author: junsli

I'll stop working on this bug. ocamldoc has a few places extracting strings
from a file only based on char position (e.g. odoc_sig.analyse_class_elements).
Location calculation could be error-prone in this situation and I don't have
good solution for this.

Here is what I got for someone who wants to hack this bug in the future.

  1. Read ocamldoc manual to learn some terminology like "special comments" and "text."
  2. Use "make debug" to compile a ocamldoc that prints debug information.
  3. The first place to look at is odoc_comments.ml. It splits each special
    comment into "description" and "remain" and then parse them (see odoc_text.ml)
    to extract element information. Currently they are just string, so we need to
    attach location info to them, along this line:

type loc_str = { str : string; start_p : Lexing.position; }

(i.e. add a start position for the string)

  1. Location info should be passed from one parser to another parser. Look at
    odoc_lexer.mll and odoc_parser.mly to see how special comments are extracted,
    and how "description" and "remain" are splitted. Also look at
    odoc_text_lexer.mll and odoc_text_parser.mly. They are used to parse the
    element information inside a special comment.

  2. special comments currently are extracted from the file, and only the comment
    string fragment is parsed (thus global location information is lost). The first
    step to fix this is to add the location information in odoc_lexer.mll:

    %type <(Odoc_types.loc_str * (Odoc_types.loc_str option)) option> main

and let the type system lead the change.

  1. odoc_ast.ml odoc_sig.ml call all_special function to get all special
    comments in a string. This chould be the place to initially pass the location
    of the string to the lexer. But it requires more work here, as the design of
    functions of Info_retriever does not work well with location information. I
    suspect we need re-design a bit of the workflow of ocamldoc parsing (or at
    least Info_retriever should provide a better way to work with location information)

Note: Location.t contains location information for comments in interface and
implementation files. Location.t is used in ast. See odoc_sig how this location
is used.

@github-actions
Copy link

This issue has been open one year with no activity. Consequently, it is being marked with the "stale" label. What this means is that the issue will be automatically closed in 30 days unless more comments are added or the "stale" label is removed. Comments that provide new information on the issue are especially welcome: is it still reproducible? did it appear in other contexts? how critical is it? etc.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant