opensimulationinterface/proto2cpp

Fork of proto2cpp:

Doxygen filter for Google Protocol Buffers .proto files

How to enable this filter in Doxygen:

1. Generate Doxygen configuration file with command 'doxygen -g ': e.g. doxygen -g doxyfile
2. In the Doxygen configuration file, find FILE_PATTERNS and add *.proto: FILE_PATTERNS = *.proto
3. In the Doxygen configuration file, find EXTENSION_MAPPING and add proto=C++: EXTENSION_MAPPING = proto=C++
4. In the Doxygen configuration file, find INPUT_FILTER and add this script: INPUT_FILTER = "python proto2cpp.py"
5. Run Doxygen with the modified configuration: doxygen doxyfile

Following change is recommended by Timo Marjoniemi but must not be used: In the Doxygen configuration file, find JAVADOC_AUTOBRIEF and set it enabled: JAVADOC_AUTOBRIEF = YES

Version history

0.8-beta (2018-12-09) OSI

• Bugfix regarding long comments, remove typo
• Bugfix and extensions have been made by Open Simulation Interface (OSI) Carsten Kuebler https://github.com/OpenSimulationInterface

0.7-beta (2018-04-19) OSI

• Include changes from University of California.
• Support for all OSI *.proto files.
• Separate statement and comments to treat both parts differently (remove bugs regarding string modifications).
• Remove "option" statements.
• Add support for "extend" statements.
• Change "repeat" from Template to standard member. --> Better collaboration diagrams.
• Fix problems with references of nested messages (replace "." with "::").
• Change mapping from C to C++.
• Bugfix and extensions have been made by Open Simulation Interface (OSI) Carsten Kuebler https://github.com/OpenSimulationInterface

0.6-beta (2015-07-27)

• made output to be more compact by removing extra empty lines and not moving member comments before the member but keeping it after the member instead
  • these changes lead into need of enabling JAVADOC_AUTOBRIEF
• added steps for enabling the filter in Doxygen in this file

0.5-beta (2014-11-16)

• fixed enum ending to have semicolon to have proper enum syntax in struct (thanks to m47iast for pointing this out)

0.4-beta (2013-08-29)

• 'classified' proto2cpp and updated documentation to make the script itself Doxygen compatible
• changed all print statements to print() functions
  • 64-bit Python v3.3.1 running on 64-bit Windows 7 Home Premium did not automatically convert print statements to print() functions but instead raised a syntax error
• made a change so that .proto files are converted before printing and other files are printed to stdout as is
  • this allows using the filter with multiple file types

0.3-alpha (2013-01-29)

• moved .proto file parsing logic to another function
• added comments to the file

0.2-pre-alpha (2012-06-15)

• added support for enums

0.1-pre-alpha (2012-06-13)

• initial version

Copyright

Version 0.7-beta -

Extensions for Open Simulation Interface - License MIT

Version 0.7-beta

Copyright (C) 2016 Regents of the University of California https://github.com/vgteam/vg

Version 0.1-beta - 0.6-beta

Copyright (C) 2012-2015 Timo Marjoniemi https://sourceforge.net/p/proto2cpp/wiki/Home/

proto2cpp's Issues

Where to copy the repo content?

i think i have not correctly copied the content of the repo. can you explain what does the "desired path to proto2cpp.py" means? i dont understand it i tried copying it in CMakeLists.txt folderbut it doesnt work. need help!!!

Describe idea behind proto2cpp

Add content to idea_proto2cpp.adoc .

Describe enabling the filter

Add content to enabling_filter.adoc.

The proto2cpp.py regex for replacing . with :: can clobber natural punctuation in comments

Describe the bug

All full stops (periods) '.' occurring in comments are replaced with :: even when they don't result in a reference.

Describe how to reproduce the bug

Steps to reproduce the behavior:

1. Write the following documentation string:

/**
 * This documentation is quite long.
 *
 * It needs more than once sentence to describe what is happening.
 * 
 * FullyStopped.value is a reference, but FullyStopped.
 *                                  value is not.
 */
message  FullyStopped {
    required uint32 value = 1;
};

2. Generate documentation:

<detaileddescription>
  <para>This documentation is quite long::</para>
  <para>It needs more than once sentence to describe what is happening::</para>
  <para>
    <ref refid="structFullyStopped_1a8defeb7fb78806a0c55bfec7b89e6500" kindref="member">FullyStopped::value</ref> 
       is a reference, but <ref refid="structFullyStopped" kindref="compound">FullyStopped</ref>:: value is not:: </para>    </detaileddescription>

Converted to markdown for readability:

This documentation is quite long::

It needs more than once sentence to describe what is happening::

FullyStopped::value is a reference, but FullyStopped:: value is not

Describe the expected behavior

'.' characters should not be replaced if they are not followed by a set of non-whitespace characters

This documentation is quite long.

It needs more than once sentence to describe what is happening.

FullyStopped::value is a reference, but FullyStopped. value is not

Show some screenshots

Not Applicable

Describe the OS you are using

• OS: Debian 10
• Language: Protobuf, Doxygen, and English
• Version: proto2cpp.py@3e30b94615d64cf02713b23060f985f953751bb8 (v0.8-beta)

Additional context

A patch:

The (\S+) group requires the . to be followed by at least one (1) non whitespace character.

Any whitespace following a :: would be invalid syntax in C++ anyway, so I don't think this would break that many intentional references. Considering a sentence not followed by white space, like this one.I believe that would be invalid syntax in English.

diff --git a/proto2cpp.py b/proto2cpp.py
index a355aaa..6f0d80a 100644
--- a/proto2cpp.py
+++ b/proto2cpp.py
@@ -183,7 +183,8 @@ class proto2cpp:
         isMultilineComment = False
 
       # line = line.replace(".", "::") but not in quoted strings (Necessary for import statement)
-      line = re.sub(r'\.(?=(?:[^"]*"[^"]*")*[^"]*$)',r'::',line)
+      # also not if the "." was the final character in the line or was followed by whitespace (natural punctuation)
+      line = re.sub(r'\.(?=(?:[^"]*"[^"]*")*[^"]*$)(\S+)',r'::\1',line)
 
       # Search for " option ...;", remove it
       line = re.sub(r'\boption\b[^;]+;', r'', line)

oneof fields are not handled properly

Example

Input

syntax = "proto3";

package test;

message SubType {
    enum Type {
        TYPE_1 = 0;
        TYPE_2 = 1;
    }

    Type field_1 = 1;
    uint64 field_2 = 2;

    oneof OneOfField {
        int32 field_3 = 3;
        double field_6 = 6;
    }
}

Output

syntax = "proto3";
namespace test {
struct SubType {
enum Type {
TYPE_1 = 0,
TYPE_2 = 1,
};
Type field_1 = 1;
uint64 field_2 = 2;
oneof OneOfField {
int32 field_3 = 3;
double field_6 = 6;
};
};
}

In documentation, one would expect that field_3 could be referenced as test::SubType::field_3 or test::SubType::OneOfField::field_3. However, the field is not accessible as oneof is not a C++ type.

Once the style is chosen (i.e, test::SubType3::field_3 or test::SubType3::OneOfField::field_3) the fix is relatively simple.

Add formalities to docs

Add content to:

• releases.adoc
• copyright.adoc

Migration to AsciiDoc: Set up initial document structure

Context

Set up the initial structure of the new documentation website, based on AsciiDoc.
This issue is part of resolving #494.

Goals

• Create initial outline of documentation to enable discussion.
• Create files to enable migration of CI to AsciiDoc early.

Tasks

• Create document map.
• Create initial document structure (files with headings only, include in map).
• Fill topics with blind text.

doxygen bug

Large proto documentations may lead to some unexpected '*' or previous '///' in the html documentation.