Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0005901OCamlocamldocpublic2013-01-22 22:412016-03-19 20:48
ReporterHendrik Tews 
Assigned Toguesdon 
PlatformOSOS Version
Product Version4.00.1 
Target VersionFixed in Version 
Summary0005901: please provide location info for warnings

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.


Attached Files

- Relationships
duplicate of 0001964closed more helpful ocamldoc warnings 
related to 0007084acknowledged ocamldoc parsing error issues incorrect line number 
related to 0007187closedgasche Line numbers in ocamldoc errors are wrong 

-  Notes
gasche (developer)
2013-07-28 23:35

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.
junsli (reporter)
2015-11-24 03:23

Hello, what's the plan on this bug? I'd like to fix it.
gasche (developer)
2015-11-24 09:37

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.)
junsli (reporter)
2015-11-24 17:41

Hi gasche, Thanks. I meant the target plan, but I guess it does not matter. I'll work on this anyway.
junsli (reporter)
2015-12-22 07:17

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.
junsli (reporter)
2015-12-29 23:06

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 It splits each special
comment into "description" and "remain" and then parse them (see
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)

4. 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.

5. 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.

6. 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.

- Issue History
Date Modified Username Field Change
2013-01-22 22:41 Hendrik Tews New Issue
2013-01-22 22:41 Hendrik Tews Status new => assigned
2013-01-22 22:41 Hendrik Tews Assigned To => guesdon
2013-07-28 23:33 gasche Tag Attached: junior_job
2013-07-28 23:35 gasche Note Added: 0009953
2013-07-29 07:32 gasche Relationship added duplicate of 0001964
2015-11-24 03:23 junsli Note Added: 0014816
2015-11-24 09:37 gasche Note Added: 0014817
2015-11-24 17:41 junsli Note Added: 0014828
2015-12-11 06:56 gasche Relationship added related to 0007084
2015-12-22 07:17 junsli Note Added: 0015186
2015-12-29 23:06 junsli Note Added: 0015204
2016-03-19 20:48 gasche Relationship added related to 0007187
2017-02-23 16:46 doligez Category OCamldoc => ocamldoc

Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker